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1 Overview 


‘This manual documents APL as provided in systems from Iverson Software 


Inc. 


Introduction 


This dialect of APL is based on Version 20 of SHARP APL. 


by Example 


This section shows what you would see on your screen after starting APL 


and 


entering а few simple lines. ‘Type the APL symbols - x + P by 


pressing the ALT key and typing p - = r. 


2+3 


prices-6 4 2.5 3 
orders 3 1.5 0 2 
costseordersxprices 
*/costs 


(+/costs)+Pcosts 


Figure 1—1 : Elementary examples to illustrate some aspects of APL. 


February 1993 


Interaction. You enter the first input from the keyboard: 


243 


As soon as you press the Enter key, APL executes the sentence you 
have just entered and the result 5 appears. 

Dialogue. To show that it is ready for new input, APL moves the 
cursor from the left edge to six positions to the right. Now you can 
enter something else. The dialogue is clear because what you type is 
indented and what the computer replies is not. 


Overview 1-1 
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. Parts of speech. The grammar of APL is described in terms like those 
used to describe natural language. In the example, you can sec the 
ptincipal parts of speech: 

* Nouns are numbers (such as 2 or 3 1 0 2) or characters (such 
as ‘abc’, To indicate that what you write is a character, or a set 
of characters, you place a quote mark (') at the beginning and 
another at the end, as you do in English 


• Pronouns are names arbitrarily assigned to nouns. In the example, 
orders is а pronoun that stands for the noun 3 1.5 0 2, and 
costs is a pronoun assigned to the result of multiplying orders 
by prices. A pronoun is thus equivalent to what mathematicians 
call a variable. k is variable in the sense that (like a pronoun in 
natural language) it docs not have a fixed meaning, but can be 
associated with different nouns at different times. 


Verbs (such as + of x) act upon nouns or pronouns. 


Adverbs (such as /) and conjunctions (such as 5) apply to verbs io 
produce related verbs. For example, in +/ the adverb / modifies 
+ (addition) to produce a verb you might сай "summation." The 
dot conjunction . produces a verb which performs inner product 
on matrices or tables. 


Is (or, as grammarians say, the copula) links a thing and some 
attribute. APL uses · to link а pronoun and the name (or pronoun) 
assigned to it. A sentence such as 


rate«l.6 
may be read as "rate is 1.6." 


« Collective nouns. A noun may be a single number or character or 
a collection of many numbers or many characters known by a single 
name. Because the members of such a collective noun are arranged 
rectangularly, a noun is said to be an array. Collective nouns include 
lists or tables, as well as higher-rank arrays. The simplest possible 
array has no rows or columns, and consists of a single item. APL 
allows direct use of a collection. That is, in many situations, an APL 
sentence is written the same way regardless of whether a noun in the 
sentence consists of a single item or many items. 


No declarations. Some programming languages require that you state 
in advance the type and shape of data to which a name will refer. In 
general, APL does not use declarations. 


Display, APL sutomatically displays the result of a calculation (unless 
you tell it do something else with the result). It is not necessary lo 


1-2 Overview 
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request display or 10 tell APL how to format it (although you may, 
when you want a different format). 
User-defined verbs. New verbs can be created and given arbitrary 


names. In other respects, they are used in the same way as other 
verbs. 


. Saved workspaces, You can build on work done earlier by making use 
of saved workspaces. 


Programs. Programming is the creation of new verbs. In other lan- 
guages, these may be called programs of functions or procedures. The 
APL system provides both а line editor and a full-screen editor to help 
you enter or revise definitions. 

Nested definitions, A verb may refer to other user-defined verbs in its 
definition. A verb can also refer to itself; а verb that does so is said 
to be recursive. 


Reading and speaking. Because of the similarities between the gram- 


mar of APL and the grammar of a natural language such as English, 
a well-written APL sentence may be read aloud with clarity. For ex- 


ample: 
ргісезеб 4 2 3 “Prices are б, 4, 2, and 3.” 
-/(f/prices),L/príces “Difference between the 
4 maximum and minimum 
prices.” 
Nodd- ltevens2x+\6P1 “The cumulative sums 
1 4 9 16 25 36 of odd, which is 1 less 
than even, which is 
twice the cumulative 


sums of 6 ones.” 


Arrays 


With the exception of packages, every noun is an array. APL also provides 
а noun called a package.) An array is composed of any number of items, 
arranged along any number of axes or dimensions. 
There is no special procedure for saying “This is ап amay,” since every 
noun is automatically an array. An array thal contains only one item and 
has no axes at all is just а particular case of an array, called a scalar. 
i A package in special type of noua with sme useful proportion for wating disparate object tret A Nfg . 
described in 


за ба aray - io vais member мо fed by name ruber than by postion. Packages are 
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When a verb refers to a noun, it refers 10 the array as a whole. Depending 
on what the verb is and how it is used (and how it may be modified by 
adverbs), the verb either treats the entire array collectively, or considers the 
array to be a sel of cells, so that the verb applies to each of the cells in 
parallel fashion. 


Arrays are homogeneous. That is, all the items within an array must be 
of the same type. The type of item within an array determines the type of 
array. 

An item - and thus an array — may be: 

» Numeric. Numbers in APL may be Boolean, integer, real, or complex. 

. Character. For example, ., 'cost'. 

e Box. A box is а single item that contains an array enclosed within 
iL As long as the box remains closed, it can occupy a single position 
in an array, just as a single number or a single character can. Boxes 
permit data of differing types and irregularly shaped data to be stored 
in a regular rectangular framework. 


Origins of APL 


APL grew from proposals for a notation for the representalion of algorithms 
put forward by Dr. Kenneth E. Iverson and published in his seminal work 
A Programming Language? in 1966 the initial letters of the book's title 
were adopted as а name for the language. 


Dr. Iverson's proposals extended existing conventions of arithmetic and 
algebra to embrace computation. He made extensive use of common math- 
ematical symbols. In addition, he followed standard mathematical practice 
in assigning meanings to existing special symbols (for example, the Greek 
letters iota, tho, and epsilon) and in coining new but mnemonic symbols 
(for example, u for transpose). 


Iverson’ notation existed — and continues to exist — independently of com- 
puter systems to execute it. It provides a ready means of expression wher- 
ever people need 10 discuss formulas or procedures: in books, on black- 
boards, or even the backs of envelopes. Publications written in APL? 

appeared before any attempt had been made to build an APL computer 
system. APL is used in several texts simply as a vehicle for describing 
а procedure to human readers. The attraction of the language is that it 
provides a rich set of convenient and powerful operations as primitives, 


2 New York: Wiley, 1962. 


3 For example, Iverson, Sussenguth and Ракой, “A Formal Description of System/360," IBM Systems Journal, vol. 3, 
‘November 1964, 
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each denoted by a single symbol. Because of that, APL permits very con- 
cise statement of common procedures from business, finance, engineering, 
mathematics, and 20 on. 


Development Related to Array Processing 


APL borrowed from matrix algebra the idea that an operation may be de- 
fined on an array as a whole rather than on cach of its elements separately. 
Because of this, many procedures that in other languages require indexes 
and loops can be written much more simply in APL. Several texts take 
advaniage of this fact to present parallel discussion in matrix algebra (for 
continuity with the published literature, for example in economics or stalia- 
tics) and in APL (for immediate execution at ап APL device).* 

Since во much of data processing involves the analysis of data arrays, the 
fact that APL operations apply directly to arrays often makes APL programs 
simpler and shorter than programs written in other languages. Because of 
its array orientation, APL requires much less iteration, looping, testing, and 
branching. API. lacks constructs that correspond to the DO, FOR, or WHILE 
instructions of some other languages. 


Also because of its array orientation, APL is rich in verbs for the manipu- 
lation of arrays: shape, reshape, rotate, transpose, take or drop part of ап 
array, compress, expand, replicate, and so on. Because these array opera- 
tions are little described in conventional arithmetic, there are no established 
symbols for them; verbs dealing with array manipulation account for many 
of APL's coined symbols. 

APL includes provision for indexing; that is, selecting individual items from 
within an array. However, APL programs often make leas use of indexing 
than would be required in languages whose verbs are defined only on single 
items. Moreover, the APL interpreter is designed for efficient processing 
of verbs applied to an entire array, so that a program written to exploit the 
extensive array-handling powers of APL usually runs faster than a program 
defined iteratively for individual elements. 


A number of recent additions to the language continue to develop the treat- 
ment of arrays. Foremost of these is the concept of rank, and the related 
ideas of сей and frame. Briefly, an array of data is considered to consist 
of cells, Each cell provides the data for a single case. For example, а 
single case might be a table, requiring two axes (rows and columns). The 
cells are arranged in a frame, which may itself have any number of axes. 
‘An operation is applied throughout the frame. It is applied automatically 
to each of the cells without the need to write loops, tests, or iterations. 
The concept of rank is pervasive in “A Dictionary of APL,” and widely 


| For example, APL\ 360 with Statistical Applications, by Keith W. Зайда, Addison-Wesley, 1974. 
February 1993 Overview 1-5 


SHARP APL Reference Manual 


of the uses of rank ме given. 
Macicy. APL Quote Quad, vo TB, na, 7, 1908. 


mentioned in this manual,’ even though APL does not provide all of the 
uses of rank described in “A Dictionary of APL.” 


Another development in the language is the addition of boxes. A box is an 
item. It occupies a single point in an array, just as a number or a character 
occupies a single point. However, when you open the box, it may contain 
эп array of any type or shape or size. Thus, the regular structure of an 
array may contain other arrays within it.“ 


Interpretive Basis for APL 


APL. is interpretive rather than compiled. That із, a program written in 
APL is stored in the machine in more or less the form in which it was 
written, The machine does not attempt to attach meaning to the words 
or symbols, or to assign space in which to store data, until a sentence is 
actually executed. 


There are some costs in delaying interpretation until the moment of exe- 
cution. There are also important benefits, The costs are minimized when 
programs make use of APL's power to deal with arrays, since a single 
symbol or expression may invoke a great deal of processing. 


The great advantage of interpretation to the developer of а program, or to 
an informed user, is that it is 30 easy to make corrections or changes to the 
program as it goes along. Each time the program halts, whether in response 
to an error ог to an interrupt signaled from the keyboard, you can display 
the values of intermediate results, look at or modify the program, and then 
resume work. It is even possible (although not necessarily a good idea) to 
start running a program before many of its parts are defined and fill them 
in as the need arises. 


R. Bernedty, "Aa Introduction to Function Rank,” , Association for Computing 


* Дафе APL lierarure, an array whose members ме boxes has been variously called n general итиў, a nested array, an. 


enclosed urey, sod m array of arrays. 
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Grammar 


APL is an imperative language; its sentences do not make assertions or 
ask questions, but issue instructions. In natural language, the subject of an 
imperative sentence is not stated. Similarly, in APL sentences are addressed 
to an unidentified interpreter whose task is to carry them out. 


APL Syntax 


The APL system executes sentences written in the APL language. To in- 
terpret a sentence correctly, the interpreter must observe the language's 
grammatical rules. You, the human user of APL, need a similar under- 
standing, both so you can interpret sentences you read and зо you can write 
sentences that, when executed, do what you intend. This chapter describes 
APL's grammar. 


Syntactic Classes 


‘The syntax of a language is the body of rules that govern the way sentences 
are assembled. A sentence in APL is put together from names and symbols. 
‘They fall into the following syntactic classes: 


Noun A noun is made up of numbers, characters, or boxes arranged. 
in an array. A noun may also be а package. 


Constant A noun whose value occurs directly in a sentence (for ex- 
ample, the numbers 1 2.2 3 of the characters abc"). 


Pronoun An arbitrary name that has been assigned to a noun, so that 
опе may refer to the noun by using its name. It is called 
a pronoun because the name is an arbitrary substitute that 
is understood to refer to the value most recently assigned to 
iL In mathematics, a pronoun is commonly called a variable 
because the value to which it refers may vary. 
Fundamentally, the aim of data processing is to transform 
the nouns (data) that you have to some other nouns that you 
find more useful, more interesting, ог more convenient. Both 
the input and the output are - by and large — nouns. 
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Verb A verb! specifies an action to be taken. In general, a verb 
applies to а noun or а pair of nouns and produces a noun as 
its result, Defining verbs is thus central to data processing: 
verbs transform the nouns you have to the nouns you would 
rather have. 


The noun to which a verb applies in a particular sentence 
is called the verb's argument. In APL, a verb may take no 
arguments, one argument noun (to its right) or two argument 
nouns (one on either side). 

Primitive verb A primitive verb is one defined in the APL language. It is 
“built in” to the APL system, so that its meaning is always 
known to the interpreter. Each primitive verb is denoted by 
а single symbol such as +. The primitive verbs are described 
individually in Chapter 5, “Verbs”. 

System verbs The interpreter also recognizes a set of system verbs that de- 
note extensions to the APL language for which no symbol 
has been designated. Each has a distinguished name consist- 
ing of the symbol O followed by certain letters. They are 
described individually in Chapter 11, “System Nouns and 
Verbs”. 

User-defined verb A user-defined verb has an arbitrary name rather than а sym- 
bol. Its definition consists of a header that declares its name 
and establishes intemal names for its arguments and result, 
and a body consisting of lines containing APL sentences that 
describe how the verb arrives at its result, You use a de- 
fined verb in much the same way as a primitive verb; like 
a primitive verb, it may take either one or two arguments.’ 
Creating а user-defined verb in effect extends the APL lan- 
guage. Once you have defined a new verb, you can execute 
it or make use of it in the definitions of other verbs, Pro- 
gramming is the art of writing definitions for user-defined 
verbs. 


Adverb An adverb modifies the action of a verb to produce a new 
verb. Each adverb is denoted by a symbol. The adverbs are 
described individually in Chapter 6, “Adverbs and Conjunc- 
tions”. 

Conjunction A conjunction modifies the action of а pair of verbs, or a 
verb and а noun, to produce a new verb, Each conjunction 


‘Also called e function or a program 
Iti Alo рома i define а veo tot ttt na arguments, and which afore behaves Like a sou; itn value . 
result returned by executing the ve 
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is denoted by a symbol. The conjunctions are described 
individually in Chapter 6, “Adverts and Conjunctions”. 

Copula Like “is” in English, the copula + links a name to the noun 
being named. Also called assignment. 

Branch The branch arrow -= alters the sequence in which the tines 
of a user-defined verb are executed, Used from the keyboard 
or in the recovery expression of It rap it may also restart 
execution of a verb whose execution has been suspended. 


Punctuation Instructions written in APL are grouped into phrases, sen- 
tences, and paragraphs, just as they arc in а natural language. 
Parentheses are the principal punctuation in APL; as in natu- 
ral language and in conventional mathematics, they set off a 
phrase that must be treated as a unit. APL also uses certain 
other delimiters. 


Evaluation 


To evaluate a sentence is to replace each of its adverbs or conjunctions and 
their arguments with the resulting verb, and then to replace each verb and 
its argumenis with the resulting noun. You end up with a noun (unless the 
sentence has no result). 

The APL interpreter either displays the result (when you did not say what 
else you wanted done with it) or passes it on to be stored or to be processed 
by some other verb. 


Order of Execution 
When a sentence contains just one verb and its arguments, all that is required 
is to execule the verb. When а sentence contains several verbs, or both verbs 
and adverbs, you have to have rules to decide what applies to what. From 
them, you can deduce the order in which to evaluate the various verbs. 


You may read an APL sentence from lefi to right. Each verb (including the 
derived verbs you get by evaluating an adverb or conjunction) applies to 
the part of the sentence to its left and the part of the sentence to its right. 
For example, in the sentence 

atbtctd 
the first division takes а as ils left argument, and btctd as its right argu- 
meni. Within the expression btctd, the divisor of bis cd. Thus: 


atbtctd =» at(bt{(ctd)) 


February 1993 Grammar 2-3 


SHARP APL Reference Manual 


Because you are reading from left to right, this arrangement is not symmet- 
fic. There is at most one noun to the left, but all the rest of the sentence. 
to the right. Another way to say the same thing is: A verb takes as its ar- 
guments the noun immediately to its left but the entire phrase to the right. 
Some authors express that by saying a verb has short scope on the left and 
long scope on the right. 


Ruthlessly Consistent Order of Execution 


APL’s rule for order of execution is applied equally to all verbs, both 
primitive and user defined. This consistency makes an APL sentence easy 
to understand. 


Nevertheless, the very consistency may surprise you. That is because APL 
does not make exceptions for certain common verbs that in ordinary algebra 
ог arithmetic are given higher precedence than other verbs. For example, 
the expression 

a*b-cxd 


is executed in exactly the same order as axbxcxd or а+Ь+с+а (just men- 
tioned). That is, the * takes as ita right argument the expression b-cxd, 
and - takes as its argument the expression cxd? 


Conventional languages use complicated orders of execution, yet are similar 
to APL when it comes to assignment. Common statements such as x=b*c 
are executed right to left — the multiplication is performed first, followed 
by the assignment. APL is simpler than other languages in that the right lo 
left execution order is preserved throughout the language, 


Infix Notation 
In APL, as in arithmetic, a verb appears between its arguments. That is, 
the verb is an infix. 
When а verb has only one argument, the argument is to the right of the 
verb. 


Ambivalence 


Valence is the number of things with which something can combine. In 
APL, the same verb can be used with two arguments (one on either side) 
and also with just one argument, on the right. Since the same verb can бе 
used either with one argument or with two, verbs are said to be ambivalent. 


in conventional algebra, tbe expression would be executed ва if it were written С аер) (ска). 
in baguages such 2s C or LISP, primitive verbs am infixes, user-defined verbs are prefixes; in PostScript, all verbs are 
postfixes. 
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For example, the symbol - appears twice in the following sentence: 
-a-b 

The first – denotes “negation”: a quantity is to have its sign reversed. The 

quantity to be negated is the difference beiween a and b. The second - is 

used with two arguments and means “subtraction.” 

As this example shows, the practice of using the same symbol with just 

‘one argument, or with arguments on both sides, is already familiar from 

arithmetic, 


Niladic, Monadic, and Dyadic Use 
When a verb is used with arguments on both sides, it is said to be a dyadic 
use of the verb. Dyadic means “dealing with two arguments.” 
When a verb is used with only one argument, it is said to be a monadic use 
of the verb. 


When a verb is used with no argument, it is said to be a niladic use of the 
verb. Verbs that are niladic can only be used that way — monadic or dyadic 
uses are forbidden. 


The phrase “dyad +” refers to the verb + when it is used dyadically. The 
phrase “monad +” refers to the verb + when it is used monadically. 


Grouping 
As in natural language, parentheses surround an expression that is to be 
treated as a whole. When you evaluate а sentence that contains parentheses, 
you have to evaluste what is inside the parentheses before you can apply 
to it a verb that is outside, For example, the expression 


(a+b)x( a-b) 


indicates that the arguments of the verb х are the entire expression a+b 
and the entire expression a-h Thus you have to evaluate both a+b and 
a-b before you can start to evaluate х. 


Parentheses are redundant when they have no effect; they have no effect 

when the order of evaluation they impose i» what the system would do 

anyway without them. Since in APL a verb applies to the entire expression 

to the right of it, it is never necessary (but not harmful) to put parentheses 

around a verb's right argument. You get the same result from : 
(atb)xa-b 


as from 
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Catb)xCa-b) 
In APL, the expression inside а set of parentheses must evaluate to a noun. 


Tree Structure of a Sentence 


The structure of a sentence can be represented by a tree. For a sentence with 
single verb, you depict the verb as the root of the tree and its arguments. 
аз the branches. 


Figure 2-1 :Tree representation of axb. 


‘Where the argument is in parentheses, draw a similar tree to represent the 
expression inside the parentheses. 


Figure 2-2; Tree representation of (a+b) x( a-b). 
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For а sentence confined to verbs and nouns, and which refrains from re- 
defining the syntactic class of йв names in mid-sentence, the tree can be 
constructed by the following (recursive) procedure:* 


« Remove redundant parentheses surrounding the sentence (if any). 
» If there is no verb, use the remaining noun. EXIT. 
. If there is a verb, connect ће root verb to its arguments, as follows: 
. The root verb is the first verb (scanning from left to right) that is 
not inside parentheses, 
+ Its lefi argument is the part of the sentence to the left of it. Its 
right argument is the part of the sentence to the right of it. 
. Apply the same rule to each of the arguments. 


Left-to-Right and Leaf-to-Root 


When the interpreter evaluates a verb, it has to know the values of the verb's 
argumenis, But а verb applies 10 the entire expression 10 its right. So the 
interpreter has to find the value of the entire expression to the right before 
it can evaluate a verb. (That is true for any interpreter, human or machine: 
you cannot evaluate the root verb until you have established values for the 
leaves.) 


The fact that APL is read from left to right requires the intezpreter, when it 
executes a sentence containing several clases, to evaluate the subordinate 
expressions (lo the right) before it can interpret the main one (at the left). 
‘This is sometimes called the “right-to-left rule. It is perhaps better called 
leaf o- too execution. Once you remove any redundant parentheses, the 
root verb of an APL sentence is the first verb not enclosed in parentheses, 


Precedence of Verbs, Adverbs, and Conjunctions 


The precedence mules of a language determine whether some verbs are 
evaluated ahead of others regardless of their position in the sentence. APL. 
has only one rule of precedence: 


* An adverb or conjunction has higher precedence than a verb. 


This is because an adverb or conjunction modifies a verb, and you cannot 
execute the verb appropriately until you know how it has been modified, 


Among themselves, all verbs have equal precedence; among themselves, 
all adverbs and conjunctions have equal precedence. 


A listing of APL programs to yroduce trees in this fashion mey be found in Berry et al, APL end Insight, paper presented 
Y Сым» APL Para, 1971; peated by APL Press, 1974. m 

That name makes it sound somehow backwards, or somebow different from ordinary mathematics. la fact this ia exactly 
фе standard rule in mathematics. 


February 1993 Grammar 2-7 


* 


SHARP APL Reference Manual 


* No verb has higher precedence than any other verb. That includes both 
primitive verbs and user-defined verbs. 


. No adverb or conjunction has higher precedence than any other adverb 
or conjunction. 


Because all verbs have equal precedence, the only determinants of order of 
execution are parentheses (in the usual way} and position in the sentence. 

Conventional algebra also gives equal precedence to arbitrary functions. 
However, it has special rules for a few common functions. It gives expo- 
entiation higher precedence than multiplication or division, and multipli- 
cation or division higher precedence than addition or subtraction? APL 
does not retain these precedence exceptions and is therefore easier to read 
and use than C-like languages. 


Precedence in a Sentence with Adverbs or Conjunctions 
An adverb takes as its argument the noun or verb that it follows. 
A conjunction takes as its arguments the verbs (or the verb and noun) on 
either side of it. 
Because adverbs and conjunctions have higher precedence than verbs, when. 
(while reading through a sentence) you come to something that is modified 
by an adverb or conjunction, you evaluate the adverb or conjunction at 
once and replace it (and its arguments) by the resulting derived verb. For 
example, in the sentence 


(a+b) r) -Cord) 


the root verb is times-rank-Ly. Reading left to right, the quantity (a+b) 
is to be multiplied. But x is modified by the rank conjunction , so you 
have to evaluate the rank conjunction before you can do anything about the 
multiplication. The conjunction's arguments are the verb x on the left and 
the noun (1, r) on the right. 


In order to evaluate *, you have to evaluate its argument (1,r). That 
done, you establish that the root verb is simes-rank-iy. lis right argument 
is: 


(rd) 
Notice that although the right end of the sentence contains the characters 


The precedence rules of conventional algebra aye veflected in eyed 


in tmbematics help express precedence. 
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(1,г)-(с+4) 


(с+а) is not subtracted from (1,r). The precedence rule means that 
(1. 7) is the argument of the conjunction 2 and gets evaluated before the 
is performed. 

Notice too that although a verb rarely requires parentheses around its right 
argument, a conjunction may indeed require them. In the foregoing exam- 
ple, omitting the parentheses around 1,г 


(arb) xi. (ot 
makes 1 the argument of the rank conjunction 9. The sentence then reads 
the quantity (a+b) times-rank-1 the quantity ,r-(c*d) 
which is not the same thing at all. 


Other Mechanisms of Grouping 
Although parentheses arc the principal mechaniam for grouping within a 
sentence, there are others that affect both execution within a sentence and 
the overall grouping of lines within а definition. They are discussed next. 


Brackets* are anomalous in APL. So are semicolons. Both date back 
to the earliest APL implementations. Both are obsolescent. That is, as the 
language develops, other more consistent mechanisms become available for 
tasks where brackets or semicolons were formerly indispensable. However, 
for the sake of consistency with old programs, the old meanings of [ and 
3 are retained, even though need for them has vanished in newer dialects 
of APL, such as J? 


Brackets Group in the Same Way as Parentheses 


The square brackets C) serve both to group the expression inside (in much 
the same way as parentheses) and also to modify whatever is to the left of 
the bracketed expression. For example, in an expression such as 


xCatb] 


the value found by evaluating a+b is used to select particular members of 
the list x. The selection index is the result of the entire expression within 
the brackets. 


^ That is, che quass brackets [ J. ia contrast fo parentheses ( >, which are curved. 

| Tis a new dialect of APL, available as shareware. 1 bas removed the soomelous features of vaditional APL. g 
aet tha ASCII character set instead of the APL character set and зо is easy 10 use in conjunction with redu 
ache and softwar, J is described а "АМАТ. "APLSO Cannes Proceedings, APL Quote Quad, vol 20, Ba. 4, 
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Brackets are used to denote the verb selection by indexing (Sce "Bracket 
Indexing” in Chapter 5, " Verbs") and certain cases of the rank conjunction 
(described in Chapter 6, “Adverbs and Conjunctions”). 


Semicolon Is a Separator 


The semicolon ; is used as a separator. There are two contexts in which it 
may be used: 
. inside brackets used for indexing an army of two or more axes 
separating expressions in side-by-side output. 
Semicolons inside brackets. Inside brackets, semicolons separate the cx- 
pressions that specify positions along the various axes of an array. Thus 
one semicolon is required for an array that has two axes, two semicolons for 
an array that has three axes, and зо on. Each of the expressions thus sepa- 


rated needs no other delimiter; in particular, it never needs to be enclosed 
in parentheses. 


As long as brackets are used for indexing, semicolons appear to be a nec- 
essary adjunct to them. The direction of evolution in APL ia to provide 
superior altematives for bracket-semicolon indexing without actually im- 
mediately ceasing to support it. 

Semicolons on mixed output. Anywhere else, semicolons separate suc- 
cessive sentences for side-by-side output to a terminal, For example, the 
sentence. * 


table-(1-24) f x 


seis the value of 1 to 24, and evaluates 1 f x and stores it as table. 
Then it displays the message. 


f(x) when i-24: 


with the value of cable to the right of it This use of semicolon was 
formerly called mixed output because (since the various arrays that are 
displayed are produced by separate sentences) there is no need for them 
to be of the same type or shape. In modem APL, the same effect can be 
produced in а more consistent manner by the verb > (link). The direction of 
evolution is to discard semicolons in mixed output. They are not mentioned 
in the ISO standard and have been dropped from several APL systems, 
although not (at this point) from APL. 

Mixed output with semicolons is permitted only at the root level of the 
sentence. A set of sentences separated by one or more semicolons may not 
be assigned a name and may not used as the argument of any verb. For 
example, 
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* (ab) 
is rejected аз a syntax error, while 

xeaib 
has the same effect as 

xea 

aib 
A set of phrases separated by semicolons may be enclosed in parentheses 
only when the parentheses surround the entire sentence (and are therefore 
redundant). For example, the outer parentheses in the following are per- 
missible but pointless: 

('a=';a;' b=tįb;' a foo bi foo b) 


Other Punctuation 


No other punctuation affects the interpretation of an APL sentence, The 
symbols. 

+ (colon) 

9 (diamond) 

" (amp) 
delimit parts of а line, but do not occur within a sentence except as they may 
be included in a character constant. (See “Scanning the Line for Quotes and 
Comments" and “Dividing the Line into Sentences,” later in this chapter.) 
The colon occurs only to mark а label on а line in a user-defined verb and 
is not part of an APL sentence. 
Similarly, the quote mark * delimits a character constant within a sentence. 
However, as will be explained in the discussion of “Analysis of an Input 
Line”, you have to resolve the use of quotes for the entire line before you 
can break it into sentences. 
Thus, apart from the anomalous usc of brackets and semicolon, grouping 
with parentheses is the only form of punctuation within an APL sentence. 


Colon and Label 


A label is a name assigned to a line within the definition of a defined verb. 
(See the discussion of labels in the section on "Localization of Names" in 
Chapter 7, “Verb Formation") 

The colon + serves to identify a label. A label is а name formed following 
the same lexical rules as for names of nouns or verbs. If a line is labeled, 
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the line must begin with the label, followed immediately by a colon. That 
js the only use of ће colon. Since there may be at most one label on à 
line, there may be st most one colon. 


Note that a label is attached to a line, not to a sentence. Thus, a line con- 
taining several sentences separated by diamonds may nevertheless contain 
only one label, and the labe] must appear first on the line. 


Lamp and Comment 


The lamp a marks the start of a comment, which is a portion of a line 
that contains text intended for the illumination of the human reader but not 
for execution by the APL interpreter. As it scans a line from lefi to right, 
when the interpreter reaches а a (other than one embedded within quotes) 
it ignores the a and everything to the right of the a on that line. 


Note that а comment is part of a Jine rather than part of a sentence. When 
several sentences appear on the same line (separated by diamonds) each 
sentence may not have its own comment, since the first comment causes 
the interpreter to disregard the remaining characters on thal line. 

Since ensures that the remainder of the line will not be executed, it docs 
not matter whether the comment contains unmatched quotes, parentheses, 
brackets, or additional comment symbols. Nor does anything written in the 
comment affect the V-editor, which might otherwise respond to bracketed 
line numbers or to the symbols V or ¥. 


Arrays 
їл general, a noun із an array,” composed of any number of items, arranged. 
along any number of axes or dimensions." 
There is no special procedure for saying “This is an array,” since every 
noun is by default an array. An array that contains only one item and has 
по axes at all is just a particular сазе of "array," sometimes called a scalar. 


When а verb refers to an array, it refers to the array as a whole. Depending 

оп what the verb is and how it is used (and how it may be modified by 

adverbs), the verb either treats the entire array collectively or considers the 

array to be a set of cells to which the verb applies in parallel fashion. 
‘The only exception is a package, а noun whose various members are identified by name rather then by position in an 
fray suctus, 


APL limits an array to a maximum of 63 axes. 
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Types of Nouns 


An APL array may be of one of three types. All the items within an array 
must be of the same type. The three types am: 


e numeric 
character 
* box. 


A box is a single item that is an encoding of an array; the array is said to 
be enclosed within it. 


No Declarations 


There is no provision in APL to declare in advance the type, shape, or 
size of а noun. The APL interpreter simply notices what each noun's type 
and shape happen to be and allocates it space as required. It chooses 
various internal forms for the storage of numbers but converts between 
them automatically. Which intemal type the system uses to store numeric 
data should concem you only insofar as it affects the amount of space 
that a stored array occupies, or as it affects the performance of primitive 
operations on that data. 

The name assigned to а noun may be reused at will and may be assigned 
to а noun of different type or shape. Thus it is acceptable to say x«6 in 
one sentence and later say xe! Friday". 


Input Modes 
‘The possible modes of interaction at a terminal аге: 
Immediate execution This is the default. 


When the first non-blank character is ) (right 
parenthesis), the line is interpreted as a system 
command. See Chapter 12, “System Commands", 
When the first non-blank character is V, the line is 
interpreted аз а call io the V-editor. See Chapter 
1, “Verb Formation”. 

Character input In response to the symbol Ol, the next line you enter 
is interpreted as character data and is retumed as 
the value of the symbol 0. See Chapter 3, “Nouns 
and Pronouns”. 


Evaluated input in response to the symbol D, the system displays 
the symbols О: оп а new line at the left margin, 
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and then moves to the next line and indents by six 
blanks. 


The next line you type is treated as a line of APL 
to be executed. Из result is retumed as the value 
of Û. You can write any APL line that would be 
acceptable in immediate execution mode, includ- 
ing a sysiem command; but you may not invoke 
the V-editor and you may not branch to a differ- 
ent line. (However, + alone to abort execution - 
the so-called “naked branch" — is acceptable and 
aborts the entire sequence that called for O. input. 
‘The input request can also be interrupted by entes- 
ing an input interrupt. See Chapter 8, “Control of 
Execution” and Chapter 3, “Nouns and Pronouns” 
for a discussion of both topics.) 


Editor input Once you have invoked the 9-editor, the next line 
you type is interpreted in the context of the edi- 
tor. In general, the editor prompts by displaying 
а line number in brackets. (See Chapter 7, “Verb 
Formation”.) 


Analysis of an Input Line 


The syntactic rules within a sentence are quite simple. Entries that you 
type from the keyboard are executed a line at a time. Interpretation does 
not start until you signal that the line is complete by pressing the Enter 
or Return key, hereafter called newline. Similarly, the interpreter executes 
the definition of a user-defined verb a tine at a . It takes a little more. 
analysis to process an entire line because the line may contain a label or 
а comment and may be divided into separate sentences by the diamond 
sentence separator. And any of these may occur inside quotes, where they 
do not count, 10 the location of quotes and comments must be analyzed 
before anything else. 


Preliminary Checks for) and v 


A line entered from the keyboard may be a system command, When the 
first non-blank character in a line ia) (the right parenthesis), APL treats 
the entire line as а aystem command (and gives it no further consideration 
as APL sentences). 


A line entered from the keyboard may invoke the V-editor. When the first 
non-blank character in а line is V (def), APL treats the entire line as an 
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invocation of the V-editor (and gives it no further consideration as APL 
sentences). 


Neither а system command nor a call to the V-editor may be part of a 
user-defined verb, 


A line may consist of one or more sentences separaicd by o, the diamond. 
However, a diamond that is part of a character constant or a comment does 
not act as а separalor. 


Scanning the Line for Quotes and Comments 


Two symbols require special attention early in the analysis of a line. They 
are the quote symbol * and the comment symbol a. Their meanings are as 
follows: 


t t Quotes. A character constant is delimited by the symbol ' before it 
and another * following it. All the characters between the quotes (but 
not the delimiting quotes themselves) are part of the constant. Within 
а quolation, two consecutive quotes denote the quote character itself. 


^ Comment. The first occurrence of a that is not part of a character 
‘constant (and thus is not enclosed within quotes) indicates the start of 
a comment. All the rest of the line is the comment and has no effect 
on the interpretation of the line. 


Since the character o between quotes or to the right of а is simply а 
character and has no power as а delimiter, you cannot divide a line into 
sentences unti] you have scanned for quotes and comments. Proceed as 
follows: 


= Note the locations of the symbols ' and a. 

. Scan left-to-right for the first a that has an even number of quotes to 
the left of it. (Zero is an even number.) That lamp and everything 
to the right of u is а comment. Discard the comment, Н is not an 
executable part of the line. 


. Count the number of quotes that remain. In a line that has an odd 
number of quotes, it is impossible to tell which characters are supposed 
to be inside and which outside the quotation. Give up. Reject the entire 
line as а syntax error, 

. Scanning from left to right, mark each character constant. A character 
‘constant starts with the бги use of a quote and runs until a closing 
quote. At а position in the sentence where a character constant has 
started but not yet ended, two consecutive quotes denote the quote 
character itself and do not serve аз a closing quote. For example, the 
sentence 
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а+'1 can''t',b 
contains а single character constant composed of the seven characters 


I can't 
• Апу о that is not inside quotes is a sentence separator. 


Dividing the Line into Sentences 


Each line commonly contains one sentence. Frequently, sentence and line 
are equivalent? When a line contains more than one sentence, the suc- 
cessive sentences are separated by the symbol o (diamond). 


The sentences in a line are executed in order from left to right. When one 
of the sentences is a branch, it may cause control to go immediately to the 
destination of the branch; if it does so, sentences further to the right are not 
executed, 


A sentence that contains no characters, or only blanks, is said to be empty. 
It does nothing, but it is not an error. 


Types of Sentences 
APL has three types of sentences: 


Branch The first nor- blank character is +. И causes control to pass 
to the linc identified by the value to the right of the arrow. 
Branching is discussed in Chapter 8, “Control of Execution”. 


Assignment The root of the sentence is the copula ~. The noun resulting 
from evaluating the expression to the right of the arrow is 
assigned the name to the left of the arrow. There is no 
display. 


Everything eise The result of the root verb is displayed.!* 


Dividing a Sentence into Words 


A word is one or more characters that, in the interpretation of a sentence, can 
be treated as a unit. For example, each of the APL symbols for a primitive 
verb or adverb is a single word, since each stands alone. However, a name 
is just one word, regardless of the number of characters required io spell 


11 "A Dictionary of APL" does not inciude diamond and assumes that line and senience ме always equivalent. 
Ji Jf it bes a result. A few primitives return no wsult; a user-defined verb may be defined so that it bae mo result. 
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it, just as a number is a single word, regardless of the number of digits 
required to represent it. 

APL uses many symbols and several punctuation marks. Bach of these 
symbols is a word by itself." When you sec one of those symbols, you 
can treat that character as a word. You know that it cannot be part of 
some other word. 


Multi-character Words 
"Words of more than one character occur in three classes: 


Name "The name assigned to a user-defined noun or verb may con- 
tain up to 77 characters. (The characters permissible in a 
name arc described later in this chapter.) 

Numeric constant Several digits, and also the decimal point, the negative sign, 
and the letters e and J, may occur in the spelling of a single 
number. The macron ^ is the negative sign; note that this 
“high minus” is not the same thing as the subtraction sign. 
A list of several numbers separated by blanks forms a single 
word, 


Character constant A character constant, аз described carlicr, is delimited by ? at 
either end. Between the delimiting quotes, the constant may 
contain any non-control characters (subject to the limitations 
of the device to enter or display them). 


Blanks 


A blank cannot occur as part of a name ог part of the representation of a 
single number. Blanks serve to separate two characters that might otherwise 
appear 10 be part of the same number or the same name. Blanks are not 
otherwise significant, except in character constants. 

Blanks are required to separate two consecutive names (for example, the 
name of a verb and its argument or the names of two user-defined verbs) 
ог а name and number.'* 


For this purpose, jider bods (such as + — bo words, but also any of tho боа marks 
EU са: Марш Qu S cargo “ward” doe ыл ly acd 


Except, of coune, when й in жыйы а quote or comment. 
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Scanning Strategy for Locating Words 
Each of the APL primitives is represented by а single symbol and is a 
single word. Because it is а single word, it needs no delimiter beside it. 
In scanning a line of APL, the following algorithm exploits that fact. The 
strategy is: 
= Locate the left most character that may be the start of a multi-character 
word. You have found the start of а possible word when: 
* the present character could be the start of a name or а constant 
and 
the preceding character could not be part of a name or constant. 
* Assume that the name or constant continues unti] you reach a character 


that could nor be part of it. Then you know that the preceding character 
was the end of the name or constant. 


Numeric Constants 


A sequence of characters may spell a numeric constant. A numeric constant 
may represent just one number or several numbers separated by blanks. For 
example, the expression 

b+3.1xa 


has a numeric constant consisting of just one number (3.1), while the 
expression 


b+3.1 72ха 


contains a single numeric constant consisting of the two numbers 3.1 and 
72. 

Blanks that аге surrounded by numbers delimit the numbers from each other 
but do not mark the end of a numeric constant. (For example, the blank 
between the 1 and the 7.) 


In a numeric constant, the first character of the first number must follow a 
character that could not be part of а constant (or must be at the start of the 
sentence). In the preceding example, the numeric constant starts after the 
symbol +. 


Scanning from left to right within the same numeric constant, the first 
character of each subsequent number must have a blank in front of it. The 
blank in front of 72 is necessary to separate 2 from 3.1; however 3. 1 
72 is a single word. 
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Complex and Exponential Number Formats 


A number may be real or complex. A complex number is written as two 
real numbers separated by the letter J; for example: 


3.195 


Thus the letter J may occur in a number, but not more than once, and only 
with a real number both before and after it. 


A real number may be written in either of two ways: decimal or exponential. 
The exponential form consists of a decimal number, the letter e, and an 
integer, for example: 


3.1е79 


Thus the letter е may occur іп a number, but not more (һап олсе (or тоге 
than once in each part of a complex number), and only with а real number 
in front of it and an integer after it. 

A number must start with one of the characters 0 through 9 or the negative 
sign ~ or the decimal point. After а number’s first character, subsequent 
characters may be any of the characters 0 through 9 or the decimal point. 
However, a number cannot contain more than one decimal point if real, or 
one in the real part and one in the imaginary part if complex. 

A number may not contain & comma; comma is a stand-alone symbol and 
thus a word in itself. 


Dot is a decimal point when it occurs next to a digit, but a conjunction 
otherwise. 


List Constants 


А constant may be a list of several numbers or characters. The general 
rule is as follows: while scanning a line from left to right, upon first 
encountering the first character of a number, assume that it may be the start 
of a numeric list. Scan rightward at two levels: 


» Look for a blank or a character that could not be part of a num- 
ber!" Since it could not be part of a number, you know that the 
preceding character is the last of this number. 

. Look for a character that could not be part of any number. К 
terminates this list of numbers. 

As you scan, you have to revise the lias of characters thet could be pert af a number. For example, when you have 


‘only seen numerals, the decimal poat tan eligible chamcter. However, once you have observed one decimal point ia а 
number, a decimal point is no longer eligible to continue the same number. 
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Similarly, a character constant forms a single word. However, the two-level 
scan is not necessary because (unlike а numeric list) a character constant 
has an explicit delimiter, the quote mark. 


After detecting the opening ', assume that it may be the start of a character 
list. Scan rightward looking for a closing quote le 


A character list is a single word. Anything adjacent io a character list 
cannot be in the same word, Hence a character constant does not need any 
additional delimiter in front of the opening quote or after the closing quote. 


Names 


А sequence of characters may spell а name. The first character of a name 
must be located at the beginning of the sentence or after a character that 
could not be part of а name. 


The first character of а name must be а member of the set considered 
alphabetic (see below) or the symbol quad (0). Names that start with O 
are called distinguished names. The only valid distinguished names are 
those recognized by the APL system; that is, although you are free to coin 
arbitrary names that start with something other than О, you are not allowed 
io coin arbitrary distinguished names. 


The “alphabetic characters” are those permitted ав the first character in 
user-defined names. The set accepted by APL contains the 52 characters 
used in English words (without diacritical marks): 


abcdefghijklmnopqrstuvwxyz 
ABCDEFGHIJKLMNOPQRSTUVWXYZ 


APL's set of alphabetic characters also includes the characters А and û; 
they are permitted in names in the same way as other alphabetic characters. 
The characters а and w may be used as names but may not form part of a 
longer name. By convention, they are used as the names for the left and 
right arguments of user-defined verbs. 


Names are not permitted to start with the characters 5А or СА. These 
prefixes are reserved for control over trace and Hop capabilities. 


Ti sequens locking ied for two аннат. since com a quib Ме arid, б» мүш» ++ басы «single 
character rather than the end of the quotion, е” 


‘Now tat word ja ы wed in a еіЫ им; th i hor, dog” а far thin аро оов wort, even oh e blank 
in the orsi юма бы in natural ‘we would тай 


and © in text but mot im the names of APL object. 
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А name continues until (scanning from left to right) you reach а character 
that could not be рап of it, After its first character, a name may contain 
any letter of the alphabetic set or а digit. A digit is one of the characters 
0 through 9. A name may not contain а blank. A name may not contain 
more than 77 characters." Figure 2-3 provides a summary of characters 
permitted in names and numeric constants. 


Permitted Permitted in а 
Name Numeric Constant 
а — 2 0123456789 
A 2 


aa 


.ej] 


0..9 
(not at start) 


(Also а or w alone) 


Figure 2-3 : Characters permitted in names and numeric constants. 


Assigning Words in a Sentence to Syntactic Classes 


To execute a sentence, you have to know what applica to what. Such 
analysis is called parsing. Identifying which verbs take which arguments 
in effect defines the order in which the verbs must be executed. Parsing 
requires identifying the syntactic class to which each word belongs. The 
syntactic class of а symbol can be determined from the chart shown in 
Figure 2-4. The syntactic class of а name is arbitrary; the interpreter 
determines that by consulting the name's entry in the workspace’s symbol 
table. 


‘APL applies stricter rules to die names of fes and workspaces. 
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Punctuation | Branch | Copula 


x 
L 
s 
v 
D 
а 
> 
m 


-+* 
1та 
=> > 
ave 
^10 
LEE 
T£! 
enu 
чт 


Figure 2-4 : Symbols in syntactic classes. 


Notes: 

. The symbol . denotes a conjunction only when it is not part of a 
number. It is part of а number when the characte on either side 
of it is a numeral. 

€ n о Thesymbols c n v are parsed as verbs even though no use has 
been defined for them. 

* In APL the symbol * occurs only as part of the dot conjunction 
and so is a special case. 2 

v 9 The symbols V and ¥ invoke the V-editor. If they occur in an 
APL sentence (except as part of a character constant), they are 
treated as undefined conjunctions. 

The rules goveming the use of these classes define the syntax of the APL 
language. in subsequent chapters, members of the various classes are de- 
scribed separately. 


n h “A Dictionary of APL” it is treated as a noun, 
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A noun is a collection of items of data - numbers or characters — treated 
together a$ à whole. For example, in the sentence 


costeindexx+/3 1.4 19 
the list of numbers 3 1.4 19 is a noun. 


А noun may be the argument of a verb; that is, the object to which the verb 
applies. In the foregoing, the noun 3 1.4 19 is the argument of the verb 
+. 


їп general, when the interpreter executes (that is, evaluates) a sentence, it 
replaces each occurrence of verb-and-arguments by the resulting noun. It 
continues this process until no verbs are left, and the entire sentence has 
been reduced to a single noun.' Thus, executing a sentence usually requires 
reducing it to a noun, which is said to be the sentence’s value (or result). 
When index has the value 2, the result of the sentence illustrated above 
is 46.6; that is, 2 times the sum of 3 1.4 19. 


You may assign а name fo а noun. When а noun has a name, you may 
refer to it by its name. However, a noun is not required to have а name. 
In the example, the noun 3 1.4 19 has no name. Nor is there a name 
for the sum of 3 1.4 19. However, the noun resulting from multiplying 
index by the sum of 3 1.4 19 is assigned the name cost. Thereafter, 
when you refer to cost, the interpreter substitutes for the name cost the 
noun 46.8. Since а name stands for a noun, in that sense а name is like a 
pronoun in natural language. In this manual, in places where no confusion 
‘would result, the terms noun and pronoun are often used interchangeably, 
since a pronoun must always be а name for а noun. 


Rank and Shape 


The items within an array are arranged in a system of axes or Cartesian 
coordinates. The rank of an array is the number of axes it has. The simplest 
array has zero axes and is called an item or, in mathematical terminology, 
а scalar. 


In principle, an array may have any number of axes; however, аз a practical 
matter, the APL interpreter permits no more than 63 axes. 


Or во noun af аЙ, when the aentence's root verb has no mpak- 
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A single item (say, the number 123.45 or the letter K:) has rank 0: it 
has no axes. A list (say, the numbers 12 24. 3 4.75 or the characters 
‘Mary Jones') has rank 1 because its items are spread along a single 
axis. A table, made up of rows and columns, has rank 2. And so on, for 
any number of axes. 


Arrays are rectangular. The shape of an array is the number of positions 
along each axis; that is, the length of cach axis. For example, in a 3-by-4 
table (having three rows and four columns), every row has the same number 
of items (four), and every column has the same number of items (three). 


The axes of an array are identified by number. The first axis is by conven- 
tion "axis 1," the next is “axis 2" and so on? 


Reporting Shape and Rank 
The monad P, pronounced ine, reports the length of each axis of a noun. 
Its result is a list containing one number for each axis. The value of each 
number indicates the length of the corresponding axis; that is, how many 
items lic along that axis. For example, when t is a table with three rows 
and four columns: 


ot 
34 


This is called “shape of t" Applying P again to find the length of the 
result of Рс (the shape of the shape of c) tells you how many items there 
эге in the noun Pt: 


ppt 
2 


Thus, two consecutive uses of monad © give you the rank of a noun. 


Arrays and Cells 


You may consider an array as a collection of cells. Each cell occupies the 
noun’s last so-many axes, The number of axes devoted to a cell is arbitrary, 
but they have to be at the end of the list of axes. Suppose you want cach 
cell to have К axes, Then the last X axes are said to be rank-k cells, ог 
simply &-cells. 


For example, suppose the noun a is created as follows: 


> In a contest whore you have elected. counting, the first exis ia axis Û, the second is axis 1, and so on. See the 
discusion of index origin in Casper Newer dislect of APL, such as J, use index origin 0 exchuively, 

9 Rho ia the name for the symbol. The verb it denotes may be used either м a monad or тё & dyad. As а monad. the verb. 
is ofen called shape; at à dyad. reshape, Sao the discussion of verb names at @ start of Chapter 5, “Чел”. 
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а+2 3 &p'abcdefghi JkInnopqrstuvwx* 


a 
abcd 
efgh 
ijkl 


mnop 
qrst 
uvwx 


Then the list ‘abcd! is a l- ell of a. The two separate 3-by-4 tables are 
2-cells of a, and the entire 2-by-3-by-4 collection is a 3-cell of a. Each of 
the individual letters is а O-cell of a. 


‘These are all valid ways of looking at the noun a. Whether you treat а as 
а single J. cell. or a pair of 2-cells, or a 2-by-3 table of 1-cells, or a 2-by- 
3-by-4 array of O-cells, does not depend on anything in a itself. How you 
look at a and partition its axes into cells depends on the verb you apply to 
а. И also depends on the way the verb is modified by the rank conjunction 
Ж. (See Chapter 6, “Adverbs and Conjunctions”.) 

The rank conjunction specifies how many of a noun’s axes are used to form 
а cell. The cell axes have to be taken from the last of the noun's axes. 
Suppose b is a rank-4 array, and that the shape of bis the list 2 3 4 5. 
When you decide to partition b into cells of rank К, in effect you are taking 
the last k items from the list 2 3 4 5 and reserving them for cells. 


When you treat the last K axes as cells, the noun may have other axes left 
over. The axes that come before the k axes you treat as cells are said to be 
the frame axes. The frame axes are the complement of the cell axes. For 
example, when the shape of bis 2 3 4, then b has: 

Frame 2 3 4 relative to cells of rank O (each of which із an item) 


Frame 2 3 relative to cells of rank 1 (cach of which is a list of 
shape 4) 
Frame 2 relative to cells of rank 2 (cach of which is a table of 
shape 3 4) 
An empty frame relative to cells of rank 3 (cach of which — there is only 
one — is the entire 2-by-3-by-4 array). 
Notice that an empty frame means that the entire array is treated whole, as 
a single cell. Figure 3-1 illustrates the aliemative ways of partitioning а 
2-by-3-by-4 array into cells. 


‘An empty frame has no frame azes. That ie not the same thing м w zero frame - one of whose ates has length zeco (and 
therefore bas ло cell). 
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Rank 0 celis Rank 1 cells Rank 2 cells 


паво 


Figure 3 -1 : Alternative ways of partitioning а 2-by-3-by-4 array into cells. 


The number of cells thai а frame contains is the product of the noun's 
frame-shape, When any of the frame axes has length 0, the number of cells. 
it contains is zero. Such a frame is said to be a zero frame. 


Complementary Partition 


An array’s cell rank is the complement of its frame rank. You can describe 
the partition by stating: 
+ the rank of cach cell (in which case any leftover leading axes are part 
of the frame) 
or 
> the rank of the frame (in which case any leflover trailing axes are part 
of each cell). 
To describe a partition by specifying the number of frame axes, use a 
negative number. The number of frame axes is the magnitude of that 
negative number; for example: 
Rank 1 The first axis is the frame, Each cell has whatever rank remains 
when the array 's first axis is devoted to the frame and all the other 
axes are cell axes. 


Rank 2 The first two axes are the frame. Each cell has whatever rank 
remains. 


For example, within the rank-3 array a mentioned earlier, the list "abcd! 
may be called a 1-сей of a or it may be called a ~2-cell of a. Similarly, 
the 1wo 3-by-4 tables within a may be called either 2-cells or ~1-cells of 
a 
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Major Cells 
For any array, its 71-cells are its major cells. The number of major cells is 
the length of the array's бги axis. A rank-O array (that is, an item, having 
no axes) has a single major cell, itself. 


Infinite Rank 


When a verb has unbounded, or infinite, rank, it treats its entire argument as 
a single cell, regardless of the number of axes the array may have. Several 
verbs have infinite argument rank. АЙ user-defined verbs have infinite rank. 
APL does not have a symbol for "infinity." When you need to specify that 
а verb applies with infinite rank, any large number will do for the rank, 
provided it is not less than the noun’s actual rank. 


Types of Noun Items 
An item may be: 
a а number 
* a character. 
e abor. 


Homogeneity of Arrays 


‘All the items in an array must be of the same type: numbers, characters, 
of boxes. 


Within an array of boxes, cach box may contain any type of array data 
(number, character, or box), with no requirement that the various boxes 
contain data of the same type. 


Empty Arrays 


An array is empty when one or more of its axes has length 0. In principle, 
the type of an empty array is immaterial. However, the verbs > and + and 
the derived verb n\ are permitted to produce а non-empty мтау from an 
empty one, and when they do, the empty array’s former type may again 
become evident. 


To facilitate work with character arrays, the empty character list ! *, or any 
empty array resulting from an operation on а character array, retains its 
identity as type character. 
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All other empty arrays are numeric. Thus (10) = Оро for any w, regard- 
Jess of the type of w (and even when wis an array of boxes). 


Numbers 

During input or output, a number is represented by digits, combined as 
needed with a decimal point, a negative sign, or the letters e or J. A 
negative number has a leading macron (or “high minus sign”), as in 3.2 
or 6.26723. 

А number may be written in any of the following forma: 

Integer For example, 2 7256. 
Real For example, 2.1 0.009 72.56. 
Exponential For example, 1.6e9 6. 2 23. 
Complex For example, 374.1 1.69 6. 26 2. 


In writing the various items in a list of numbers, it is permissible to intermix 
forms. For example, the following is perfectly valid: 


х+1 716 2.56 2.08617 3.1 6.3 


In similar fashion, when the APL interpreter displays a list of numeric 
items, it chooses the form independently for each item and thus may also 
intermix formats.* 


Although the interpreter permits mixed formats for entry or display, it stores. 
all the members of an array in the same way. The effect of a sentence such 
эз the one just shown is lo create an array all of whose items are stored in 
the most demanding of the forms (sce below). 


Internal Representations of Numbers 


The APL interpreter uses four different intemal forms for the storage of 

numbers, The forms differ in the space per element they require (so the 

choice of internal type may have important consequences for storage). The 
four types are: 

Boolean Zero or one. Boolean representation is used for a single 0 or 
1 entered from the keyboard, or for the result of a proposition, 
with 1 for true and 0 for false. Certain verbs retum Boolean 
results (for example, testa for equality and membership.) 


Storage: Bitwise, 8 items per byte, plus overhead (see be- 
low). 


in the display of flat, In wiles or higher-renk arrays, all items ae curently displayed in the 
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Integer. A number with no fractional part and within the range that 
can be represented in 32 binary bits: -2?! to 2 — 1 (thal is, 
-2147483648 to 2147483647). 


Storage: 4 bytes per item, plus overhead. 

Floating A number with а fractional part or an integer outside the 
range representable in integer format. Also known as real 
numbers. Floating point numbers may range in magnitude 
between +7.2370055773322621х10"*. The intemal represen- 
tation uses 14 hexadecimal digits, permitting a maximum pre- 
cision of about 18 decimal digits. 


Storage: 8 bytes per item, plus overhead. 

Complex A number with both real and imaginary parts. The parts are 
written with the letter J between them. Each part is repre- 
sented in Cartesian form, in the same way as a floating point 
number, 


Storage: 16 bytes per item, plus overhead. 
In addition to the space required to store its items, there is an additional 
overhead for system information, including the amay's type, rank, and 
shape, amounting to at least 12+4x its rank. 
Within a numeric array, all items are given the same type of intemal rep- 
resentation (Boolean, integer, floating, or complex). For example, the list 
1 2 is stored entirely in integer representation, even though one of its items 
Gf alone) could be stored as Boolean; similarly, the list 2 2.3 is stored 
entirely as floating, even though one of its items (if alone) could be stored 
as an integer. 
‘The existence of different intemal schemes for representing numbers shows 
up directly in the space required to store them and may also affect the time 
required to execute certain verbe. In principle, intemal type has no effect on. 
the values that a verb can accept as arguments or the values that it returns as 
result. For example, а verb whose domain is Limited to integers can accept 
any array whose values are numerically integral, regardless of whether the 
array is stored in the Boolean, integer. floating, or complex intemal type. 
‘The interpreter initially assigns the most compact representation that will 
embrace all the items in an array. Thereafter, upward conversion between 
types of numeric representation is automatic. If you write 


KO 110 


the interpreter stores x in Boolean representation. If you then catenate an 
integer to x, for example by 
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xex,2 


the interpreter converts the former value to integer representation while 
appending the integer 2. Similarly, if you then catenale floating-point 
number, for example, 

хех,1.9 
the interpreter represents the entire result in floating representation. 
‘These conversions are automatic. No declaration of type is needed or 
allowed. There are no errors resulting from “mismatched” numeric types. 
The only practical consequences involve allocation of memory, and perhaps 
execution speed. 
However, downward conversion of type, is not performed automatically. 
For example, 


xel 2 3-0 13 
could be represented as Boolean. x will, in fact, be represented as integer. 


Character Data 


To enter characters from the keyboard, you enclose them in quotes; for 
example, as "ABC! or Far away! or !3x$6*.* To represent the quote 
character itself, enter two consecutive quotes. 


‘There is no implicit collating sequence for characters. When you grade 
character data, you must provide a reference alphabet to.control the order. 


APL Character Set 


The APL interpreter represents each character intemally as one 8-bit byte. 
There are thus 256 possible characters. Not all of them are displayable or 
enterable from the keyboard, Nor are all of them valid іл a sentence to be 
executed. 


The character set includes both conventional alphabetic and numeric charac- 
ters and also characters for the additional symbols used in APL expressions. 
During output, a few characters are recognized as contro? characters (for 
example, newline, line feed or backspace). The bit-patterns that the APL 
interpreter uses to represent characters do not match the codes used in the 
EBCDIC or ASCII encodings. 
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guns 


Figure 3—2 : Internal representation of APL characters. 


February 1993 Nouns and Pronouns 3-9 


SHARP APL Reference Manual 


Boxed Arrays 


An item within an array may be a box. A box is ап item in the same sense 
that a single number or character is an item: it has no axes, and it occupies 
a single position in the array's Cartesian framework. An array consisting 
of six boxes, arranged in two rows and three columns, has shape 2 3, in 
the same way as а 2-by-3 array of numbers or characters. 


А box may contain within it an array of any rank, shape, or type. A box is 
thus a convenient way to place objects of arbitrary shape within the simple 
Cartesian framework of an array. To distinguish it from a noun that contains 
boxes, а noun whose items are unboxed numbers or characters is said to be 
open. 

A box is created by the box monad <. The result of < is always an item 
and therefore has rank 0; for example: 


PPxe«'Now is the t me! 
0 


Several ways to form an array of boxes are described in Chapter 5, “Verbs”, 
For example, the link verb > joins а pair of open arrays to form a two- 
item list of boxes. Because > boxes its right argument only when the right 
argument is open, a sentence that links a succession of open arrays produces 
а list of boxes, thus: 


oh s'»! the!» time" 
4 


y 
E DS | Мше | йү! 
{Now| | 2s] f thel It ine 

Hitt 


Partitioning 
Modifying the box verb with the conjunction cut produces the derived verb 
cut. and. box. It forms a box from each of the segments 
using the first сей! of the right argument as the delimiter. This partitions 
the right argument into a list of pieces of the argument. For example, to 
box words delimited by blanka: 


ze 1 t Now is the time! 
y*'Now!2! is!» 'the'»'rime! 


у=2 
1 ^ y and z maich 

y ¥80 2 
1111 ^ The items of y and z match 
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yiét time! 
4 a «'time' is the fourth item 


Figure 3— 3 depicts  2-by-3-by-4 array of boxes with two of them opened 
зо you can see their contents. 


Rin Tin Tin 
миа 


Figure 3—3 :A 2-by-3-by-4 array of boxes. 


Display of Boxes 


Whenever a senience produces а result but does not assign а name to it, 
the interpreter displays it. ‘This applies just as well to an array of boxes 
as to an апау of numbers or characters. Such a default display has the 
same appearance as the result produced by the thorn monad v, described 
in Chapter 5, “Verbs”, 

The appearance of a display of an array of boxes is influenced by the valus 
of the system noun Ops ("position and spacing")! Ву setting the last 
two items of Ops negative, for example Ls -O 0 2 2, you cause the 
interpreter to show the boundaries of each box. That is particularly useful 
when you want to make the structure explicit With the box boundaries 
thus made visible, the noun z (mentioned above) is displayed like this: 


Qpse0 0 72 72 
z 
111 716 


INowl | isl Ithel |¢imel 
—— Же шеш Hl 


T See Chapter 11, “System Nouns and Verbs” for the definition of Ops. 
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Packages 


A package is а noun that in some respects resembles a workspace: 
. The items within a package are selected by name rather than by position 
in а framework of axes. 
+ А package may contain both pronouns and user-defined verbs. 


+ A package is not an array. Hence, verbs that are defined on arrays are 
not defined on packages, 

Within а package, the various named objects may be of any type, including 

not only nouns of any type, but also user-defined verbs. A name in a 

package may even have no referent, so that when the contents of a package 

аге materialized into the workspace, an object having that name is expunged. 

A package is useful to provide overlays. These permit an application de- 

signer to materialize in a workspace — perhaps dynamically, or within а 

local environment — whichever nouns or verb definitions the application 

requires, without altering the package from which they are taken. Often the 

source package resides not in the workspace at all but in а file outside the 

workspace. 

A package is а data type independent of APL arrays, manipulable only by 

а set of specialized aystem verbs (pack, Opdef, еїс.). The contents of a 

package cannot be displayed directly, A sentence whose result is a package 

produces as display only the message: 

packages 

To sce the definitions of the objects stored in a package, you have to extract 

the packed items and then display them. 

Verbs for manipulating packages are listed below, with square brackets 

indicating optional arguments. For detailed descriptions, sce the entries for 

the individual verbs in Chapter 11, "System Nouns and Verbs”. 

ca) Праск w Form a package. 

Са] Dpdef w Define in the workspace objects from a package. (No 
result) 

а Dpexw Form a package by excluding some objects in a pack- 
age. 

а [pins u Form a package by merging two packages. 

Гај ПрЈосҝ w Lock the definitions of user-defined verbs in a pack- 
age. 

Opnames w  Retum the names of objects in a package. 
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(9) Орпс w Retum the name-class of objects in а package. 


[а] Oppdef w Like Opdef, but protect existing objects by defining 
only those names that do not conflict with names 
outside the package. 

а Qpsel w Form a package by selecting a subset of the objects 
in a package. 

а Opval w Retum the value of a pronoun in a package. 


Input and Output 


This section deals with the conventions for displaying data at the screen 
and with entering data from the keyboard. See also the description of the 
format verb ¥ in Chapter 5, “Verbs”, and the description of the system verb 
Urnt in Chapter 11, "System Nouns and Verbi". 


Constants 


А sentence io be executed may contain characters that represent a number or 
a list of numbers; similarly, a sentence may contain characters that denote 
the characters themselves, as text (rather than names or symbols). Such an 
entry is a constant, it tates directly the value of a noun. 


The interpreter considers а constant that consists of a single number or 
character to be an item. An entry that consists of more than one number 
or character is a list. For example, in the following, a is an item and bis 
a list: 

а+126,2 

5126.3 14 127 
There is no way to write a constant that has more than one axis. (See 
“Creating Higher-Rank Arrays," below.) 
During entry, blanks separate successive numbers in the same list; extra 
blanks are not significant. 
You may write numbers in different formats within the same list; some in 
integer formal (without а decimal point), others in real format, yet others 
in exponential format or complex format, as convenient or appropriate for 
the values you are writing. For example: 

c*1 .3 0.0125 2.62673 262e2 1.2e473 
A negative number is preceded by the macron, as for example ^5. The 


macron or "overbar" symbol is not a verb, but one of the characters used 
in writing certain numbers, just as the decimal point or the letters e or J 
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occur in certain numbers. When several numbers are negative, each must 
have its own macron. By contrast, the symbol - denotes the verb minus or 
negate and, like other verbs, applies to an entire array. The expression 


* 12 1.05 4000 
gives the name x to a three-item list; only the first item is negative, whereas 
х*-12 1.05 4000 


creates a threc-item list all of whose items are negated by the verb (=) that 
precedes them. 


To differentiate characters from numeric data, you enclose a character item 
(or a character list) in quotes. The beginning of a character constant ia 
marked by a single quote mark. Everything you enter after that (for the 
‘balance of the line) is treated as characters until you enter a matching tingle 
quote to end the string of characters. Once you have started a quote, two 
consecutive quote marks indicate the quote character itself. (See the dis- 
cussion of quote in Chapter 2, “Grammar”.) Thus, in general, numbers аге 
separated by blanks but characters are not. Extra blanks between numbers 
are not significant, Each of the following creates and names a seven-item 
list: 


xe25 72.4 1e9 2.7824 123456789 70. 21.4 0 
ye'Thanksi' 
ze'I canttct 


Within the zone enclosed by quotes, blank is a character like any other. 
When you put several consecutive blanks in a character constant, cach of 
them is an item in the same way as any other character in the string. 


When the interpreter displays character data, it does not surround it with 
quotes or double the quote mark, hence: 


z 
I can't 


А line containing an odd number of quotes (not counting quotes that occur 
within a comment) is ambiguous, The interpreter cannot tell which charac- 
ters are inside and which are outside the quotation. It rejects such a line as 
а syntax error, without executing any of it. 


Creating Higher-Rank Arrays 


A constant is limited to a single item or a list. To supply the value of a 
table (or any array with more than one axis) you have to enter it as a list 
and then restructure it with a verb such as reshape to organize the items 
into a higher-rank array. Thus: 
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te3 4P'The fat cat." 
t 

The 

fat 

cat. 


Creating the Value of a Box 


А boxed constant, like a higher-rank constant, is written as a phrase that 
includes a verb that forms boxes, In the following example, the verb link 
boxes and joins the constants to form a three-item list of boxes: 


he1 Paul! > 'Hempstead! > 1933 8 24 
3 1Ph 

Paul 

Henpstead 

1933 8 24 


Display of Nouns 


Unless the noun produced by evaluating & sentence is assigned а name, 
the inlerpreter displays the noun's value. This is called default display. 
It occurs with по need for a “display” verb and requires no instruction 
regarding format The display of numbers is conditioned by the visible 
value? of the system nouns Орр (printing precision) and Пре (page width); 
the position and spacing of boxed arrays is controlled by the visible value 
of the system noun Ops. 

The interpreter displays a list (that is, an array having only one axis) hori- 
zonially. It inserts а blank to delimit a number from its neighbor. However, 
it does not put blanks between the items of a character array. That way, 
characters can be placed side-by-side to form words, but numbers (which 
often require several characters to write) do not run together. For example 


n*123,45,67.8 


forms a three-item numeric list, When the interpreter displays the list, il 
introduces blanks to separate the items: 


n 
123 45 67.8 


But it does not insert blanks to separate the items when they are characters: 


Das the seme appearance ss the msuk of the monad Y, described im Chapar 5, "Verba". 
the workspace acd not shadowed by the localization of names. 
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cemi tel Put Itu % “ 
с 
Не11о\ 


Position and Spacing in an Array of Boxes 


During display of an array of boxes, the system noun Ops affects the 
position and spacing of the boxes. In a clear workspace, the value of 
ds is 1 7101. 

When the interpreter displays a table of boxes (or any array of rank grealer 
than 1), it first formats cach of the individual boxes separately. It then 
assembles those separate displays into а grid that retains the overall rect- 
angular shape of the array. To preserve the alignment of the grid, it pads 
the width of each small box to match the width of the widest box in that 
column. Similarly, it pads the height of each small box lo match the height 
of the tallest box in that row. The shading in Figure 5-10 illustrates the 
resulting plaid patiem. 

Because each item is located in a display cell whose height is the maximum 
in its row and whose width is the maximum in its column, an item may be 
assigned to a display cell with more rows or columns than it would need 
on its own. The first two elements of Ops specify how an undersize item 
should be positioned in the space assigned to it. The values 1 1 mean 
it should go in the top left comer of its box, with any extra space below 
and to the right. 

‘The last two elements of Ops control the way adjacent boxes are separated. 
‘The third element sets vertical spacing and the fourth horizontal. The 
magnitude is the number of additional print positions that should separate 
adjacent boxes. The default is zero print-positions vertically and one print- 
position horizontally. Thus: 


сэсэп 
Hellot Hello! 123 45 67.9 


The details of numeric formats, and the arrangement of boxed items in a 
grid for displaying arrays of rank 2 or higher, are described in the section 
on ¥ in Chapter 5, “Verbs”. 

Seo the sections oa Y in Chapter $, “Verbs” and the description of Ops in Chapter 11, “System Nouns and Verbs”. 


For discussion of these va the description of v in Chapter 3, "Verba" and the of Ops ia п, 
Fi action of thee values, э tho descipion of Y in Сыр description Caper 
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Separating Successive Columns of a Numeric Array 


In displaying a numeric array of rank 1 (a list), the interpreter formats cach 
item individually and separates successive items by one blank. 


In displaying a numeric апау whose rank is 2 or greater, the interpreter 
decides for the array as a whole whether to use real or exponential format. 
When it uses real format, it picks a total width and selects the units position 
once for the entire array, so that all columns are in а common format. 


Separating Successive Planes of Higher-Rank Arrays 


А rank-3 array appears as a set of tables. That is, a 3-by-4-by-5 array looks 
like three 4-by-5 tables, one above the other, with a blank line between the 
first and second and a blank line between the second and third. 


During display, an extra line (or Lines) is inserted between successive sub- 
arrays. One blank line is inserted between successive rank-2 sub-arrays, 
two blank lines between successive rank-3 sub-arays, and so on. 


If you examine the result of an expression such as 
xevArray 


where Array is an open array with more than two axes, you find that x 
has the same rank as Array. The display of x shows blank lines between 
its successive tables by vistue of the rank of x, not because x contains any 
added newline characters. 

However, when the system formais an array of boxes, the entire result is 
represented as a table. In that case, additional rows of blanks are inserted 
1o represent the separation between planes. When A is a 2-by-3-by-5 апау 
of characters, and [lps has its default value, 

*<А 


represents A by a sever-row table whose middle row contains only blanks. 


Folding Wide Displays 


An array retumed by the formalting verbs ¥ or Urnt is arranged without 
regard for the width available 10 display it. However, when you have 
output displayed on the screen, APL takes into acoount the length of the 
line available for display. The maximum number of print positions on a 
line is the visible value of the system noun Dpw (page width). The default, 
Ори in a clear workspace is 80. You may set it as low as 30 or as high as 
250. 


The effect of [pw depends on the rank and type of the array being displayed. 
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Folding a Character Array 


In displaying a character array, the interpreter prints no more than Пле 
characters on a line. Аз soon as it finds it has already put Qpw characters 
оп the current line and the next character is something other than newline, 
it forces a new line. It indents the continuation line by six spaces. 


А character array is broken solely by the number of characters on the line. 
No attempt is made to break at a word boundary or other “meaningful” 
place. 


When the array contains an explicit newline character (Пау 156401027, it 
is obeyed. That is, the next character is displayed at the lefi margin of the 
line below, and the length of the current line is counted from there. Thus, a 
list of characters containing explicit newlines appears with the lines folded 
at the newline characters or at Оры, whichever comes sooner on each Line. 


Folding a Numeric List 


A numeric list is displayed such that each line contains as many numbers 
as will fit without separating the characters that represent a single num ber. 
Thus, the number of characters on a line is at most Орч, but may be fewer. 
Since the number of characters required to represent each number may vary, 
the number of numbers displayed on а line may vary. So may the number 
of characters оп а line. In rare cases, with values of Opw less than 50, а 
single complex number may be split across two lines. 


When a line that will not fit within [pw is broken, the next line, and any 
subsequent lines that are continuations of the original line, are indente by 
six positions, 


Folding a Numeric Table or Higher-Rank Array 


А numeric table, ог а numeric array of any rank higher than 1, is arranged 
so that all columns have the same width. APL figures out the number 
of print positions that would be required if all the items were in a single 
column. It uses the field width thus calculated for all columns of the aray 
(regardless of the actual widths of number in a particular column). 


Using the field width just calculated, it starts at the beginning of each row 
and writes аз many fields as will fit within Оры. Then it moves to the next 
line, indents six positions, and prints as many of the remaining fields as 
will Gt within Dpw-6. It continues in that fashion until the entire row has 
been printed. Then it prints the next row. 
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Folding an Array of Boxes 
For folding in response to рю, the display of an array of boxes is treated 
in the same way as character data. ‘That is, each line is broken after [pw 
characters or at a newline character (whichever comes first), and the con- 
tinuation is indented by six positions. APL makes no attempt to preserve 
the boundaries of boxes when Ор requires folding. 


Display of an Empty Array 


An empty list appears as а blank line: a line on which nothing is printed. 
‘An empty table, or an empty array of any rank greater than 1, produces no 
display at all (not even a blank line). 

This is true not only for a table with zero rows, but also for a table with a 
positive number of rows but zero columns. Indeed, there is no display at 
all for any array whose rank is 2 or greater when zero is the length of any 
axis. 


Interface Nouns: О and O 


me symbols О and J denote the system nouns quad and quote-quad. They 
act like nouns shared with the session handler. The action of these two 
system nouns depends on whether they are used от set. A noun is said to 
be set when it is immediately to the left of the copula +, as in: 


xefoo analyze x 
It is said to be used when it occurs anywhere else, as in: 
хе foo analyze D 


Assigning a value to 0 or UI causes the noun thus assigned to be displayed. 


Evaluated Input 


In a sentence to be executed, when the symbol (1 occurs anywhere except 
immediately to the left of the copula, + (assuming no redundant blanks), it 
represents the value of an input expression to be obtained from the session 
handler. 


When, in the course of evaluating a sentence, the interpreter encounters the 
U symbol used in this way, it displays the prompt 


0: 


and awaits one line of entry. h evaluates the next line it receives in the 
same way that it would evaluate a line entered during immediate execution. 
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‘That done, it substitutes the resulting value for the D symbol and resumes 
execution of the sentence that contained О. For example, suppose you аге 
computing the growth factor of an investment that cams interest for 20 
years, compounded monthly. You want а sentence that will prompt you to 
fill in the annual interest rale but will accept an expression rather than just 
a number. The following illustrates the use of O to solicit а sentence whose 
result is then used in evaluating another sentence. 


(140)*12xYearse20 Expression containing Û 
п: aPrompt for input 

0.08412 aOne month of 8% annually 
4.926802771 ^Result 
The presence of О in the phrase (14D) causes APL to issue the prompt 


0:. 


In response to the prompt, you enter 0.08+12, to represent the monthly 
interest described by an annal rate of 8%. The interpreter evaluates 
0.08412 and substitutes the result 0.006666666667 for C) 40 thal it 
can evaluate 1+0. That done, it raises 1. 006666667 to the power 12x20 
and prints the result, indicating that the value after 20 years is nearly five 
times the initial amount. 


input in Response to O 


In response to the O: prompt, you enter опе line of input. It may contain 
any executable sentence, a invoking any primitive verb or any user-defined 
verb whose name is visible. When evaluation of that sentence is complete, 
the interpreter passes its value back to the expression that contained the D. 
In the example, the result is used as the right argument lo +, so the result 
could be anything in the domain of +. 


When, in response to the О: prompt, you enter а line containing several 
sentences separated by diamonds, the interpreter evaluates all of them, but 
the value substituted for II is the value retumed by the ast sentence 10 be 
executed, 

When, in response to the D: prompt, you do something that produces no 
sentence to evaluate (for example, you simply press Enter without writing 
a sentence, or execute a system command), the interpreter repeats the 0: 
prompt for evaluated input. 


t is acceptable to enter a system command during D-input. The interpnter 
carries out the command, However, since in this case the command docs 
not satisfy the request for an input sentence, the interpreter reissues the 


eral sentences separated by diamonds. 
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O: prompt. You could exploit this to copy into the workspace something 
that was not initially present and then use the object thus copied in your 
response to the prompt. For example: 

Supply data for analysis: 


O: 
datapoints 

value error 
datapoints 
^ 

ш 


)copy savedwork datapoints 
saved 1988-02-27 23:11:15 
0: 
datapoints 


When, in response to the D: prompt, you enter + alone (the naked right 
arrow), the interpreter abandons both the execution of D and the execution 
of the sentence that contained it, as well as anything else pending, back to 
the previous immediate-execution entry from the keyboard. (Sec Chapler 
8, "Control of Execution”.) A gentler method of halting execution is to 
enter an input interrupt (see below). Execution of ) Jad also abandons 
execution of the sentence, as well as the entire application. 


Character Input 


In a sentence to be executed, when the symbol U occurs anywhere except 
immediately to the left of the copula, assuming no redundant blanks, it 
represents а character list to be obtained from the keyboard. The inter- 
preter displays no special prompt (except as may be produced by ( output, 
described below). The interpreter awaits the entry of one line from the 
keyboard. It treats that line as characters (even if what you then enter looks 
like a sentence or a system command). It substitutes the resulting characters 
for the U symbol and resumes execution of the sentence thal contained l 
For example: 


enter даса:' De-), received. 


Ent er data „Display of the first sentence 
abcdefghijklmnopqrstuvwxyz Your entry 
26 received. Display from vec 


February 1993 Nouns and Pronouns 3-21 


„ 


SHARP APL Reference Manual 


Escape from [input and D-Input 


While the interpreter is waiting for one line of character or evaluated input, 
you can signal an input interrupt by typing CTRL+c and thereby escape 
from the request for input. 


Sending an input interrupt at any point during your response to a request 
for input - that is, at a keyboard any time before you press Enter or 
Return — causes the interpreter to abandon execution of the sentence that 
contains the O or D and to halt execution of the program that contains that 
sentence. Any characters you may have already entered on the same line 
are lost. However, if Ot rap has been set to respond io the input interrupt 
event, the trap may make it difficult or impossible to escape. See Chapter 
9, “Event Handling”. 


Explicit Output from O and O 


When the system name П or ( occurs immediately to the left of the copula 
+, the interpreter displays the value of the noun to the right of the arrow. 
A display produced this way is identical to a display produced by default 
output or by the monad ¥, with one important exception: output produced 
by D is not followed by a newline, whereas the interpreter automatically 
supplies а newline following default output or output elicited by D+. 


A series of sentences produced by П appear on successive lines, whereas а 
series of sentences produced by Ii output may accumulale on the same line. 
This allows a line of output to be built up from the results of several ex- 
pressions. For example, a program might contain the following sequence: 


J ate 

1  yeareyears(i1 

] disterecordmiles[i) 
1 rear 

] ns record was * 
J Ordisexi.6 

1 Oe kn? 

1 W+'Today''s distance: ' 
J Betodaymilesx1.6 

J +? km." 

1 


When that fragment of the program is executed (with appropriate values 
for the various names), the separate pieces of С) output fit together thus: 


Thoss have ю be in a И you were 1 eater these limes fom the keyboard for immediate stocution, the 


interpreter 


Т pronge be yout seri ar) would obscures the 
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1982's record was 89.76 km. 
Today's distance: 90.11 km. 


However, it is probably easier and faster to build the entire output array, 
then emit it with one output request, than to ше the piecemeal approach 
shown here. 


Folding of N Output 


Output produced by O is subject to [pw in the same way as other character 
output. That is, APL ends each line when it has displayed [pw characters 
and the next character is not newline, of at a newline character (whichever 
comes first). On each continuation tine, it inserts six blanks at the beginning 
of the line. 


Input on the Same Line as the Character Prompt 


You may want to display a prompt and accept input on the same line. You 
can do that by placing С) output before a request for input. For example 


* · U- ane: 
Name: John 


In the example above, the noun x receives both the characters John entered 
from the keyboard and also characters representing as much of the prompt 
as appeared on the same line with the reply. 


Where the prompt takes more than one linc (for example, because the 
prompt is a table, or contains a newline charactez), only the part of the 
prompt that occurs on the same line as the input is represented in the result. 
When the interpreter has displayed the prompt and is ready to receive your 
reply, the cursor is at the next position to the right. Using _ to show where 
the cunor is, it looks like this: 


Name: 


If you simply key the four letters J o h n without first moving the cursor 
somewhere else, the result contains ten characters. The first six are the 
characters from the prompt, and the last four are the letters you entered: 
John. 
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However, if you move the cursor leftward into the prompt zone and there 
enter some other characters (overwriting the characters used in the prompt), 
the characters you substitute are reproduced in the result. 


Discarding the Prompt 


When you have no interest in the prompt or in entries placed in the prompt 
zone, you may simply discard them from the result. Phrases such as the 
following are common: | 


prompte'Supply name: 
name+(Pprompt) - prompt 


Alternatively, you can exploit a quirk of az bout to eliminate the prompt 
from the result: 


prompt · supply пале: * | 
prompt о Darbout '' o nane · U 


Interposing any use of Qarbout between the input and output uses of 0 
discards the output from the [input buffer and prevents the prompt Zone 
from being treated as past of the input line. (The verb Darbout is described 
in Chapter 11, “System Nouns and Verbs“) 
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4 Naming Nouns and Verbs 


This chapter discusses how names are used and the means by which nouns 
and verbs acquire names. 


Copula 
The Jef arrow + assigns а name to something. For example 
xeanalyze data 
gives the name x to the noun that results from evaluating the expression 
analyze data 


The symbol + plays іл APL the same role that the copula “is” plays in 
English. An expression such as 


агеа+6х8 


is often read as “Area is six times eight." Because the arrow + assigns а 
name to an object, it is often called assignment. 


Once а noun has been named, further reference to the name is a reference 
to the noun's value; for example: 


areae6x8 
area 
48 
агеа*0,5 
6.92820323 


Workspace: The Universe of Names 


In order to evaluate a sentence that contains names, the interpreter requires 
tome means of keeping track of the names that have been defined and what 
each name refers to. The mapping from names to their referents is provided 
by the symbol table. The set of all names maintained by а symbol table, 
along with their meanings, is called a workspace. 
тете Dry em e ud жылш E AE re de 
жога object in а workspace whose symbol ubie gives 
benefits of linkage without any specii process of lnk editag. EC е 
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A workspace is not only the domain in which a common set of names |s 
maintained by а symbol table, but also а block of physical storage, 
area of the computer in which computation takes place is called the acti 
workspace. The aysiem command ) save sets aside а copy of the acti 
workspace's symbol table and all the objects referred to in it and retais 
it in inactive permanent storage. A workspace is thus both the conceptual 
universe in which names have meaning and a unit of storage. By saving 
a workspace, you set aside a copy of it. By subsequently loading а saved 
workspace, you restore in the active workspace all the names and all thejr 
Teferents as they were at the time the workspace was saved. 


Localization of Names 


А user-defined verb? may declare certain names to be local to itself. 
means that the verb (or any verb it invokes) may make itt own use of the 
names local to it, independent of any use those names may have outside 
the verb. Localization has these effects: 

« H assures ће verb’s author that internal names needed by the verb will 
be available to it. 

a H protects names in the workspace from possible conflicting uses 
within the verb's definition. 

« It hides more global usc of those names, if any, since from within a 
verb (or any verb it invokes), only the most local use of a name lis 
visible. 

. It cleans up after execution of а verb. When execution of а verb is 
complete, that ends its local use of names; the named objects it created 
vanish, and the interpreter frees any storage й had devoted to them, 


А name is made local to a verb by appearing in the verb's header. The 
names used for the arguments and result of a user-defined verb are мир- 
matically local to it. So are any line labels used in the verb's definition. 
(Localization of names is discussed further in Chapter 7, “Verb Formation” 
and Chapter 8, “Control of Execution”.) 7 
When none of the currently-active verbs has localized a particular nanje, 
that name is global to the workspace. But when a name has been localized 
in а defined verb currently being executed, that loca] use is understood. 


‘When a name is not local to the current verb, but is local to а pendent verb 
{a verb whose execution has been tuned but not completed), the use local 
to the pendent verb is understood. 


2 Soo Chapter 2, “Grammar” and Chapter 7, "Verb Formation”. 


| 
| 
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A declaration of local use prevents secing, changing, or creating a use 
of that name at a more global level. (It is the declaration that counts; it 
does not matter whether the localized name has actually been used.) Local 
use blocks the view of more global use; the most local use of а name is 
sometimes called the visible use of the name; a more global use is called a 
Shadowed occurrence of the name. 


Reassignment and Name Conflicts 


"When you use the copula to name something, the name to the left of the 
arrow must be free for use, that is, it must have no visible use as а verb or 
as a label. 


. When there has been no prior use, the copula assigns the name to the 
left of the arrow to the noun to the right of the arrow. 

. When the name is already in use and refers to a noun, the value to the 
right of the = replaces the former value. (That is why the name of a 
noun is also called a variable: its value can be changed at will.) 


Names for User-Defined Objects 


Both nouns and verbs may be given arbitrary names. As mentioned earlier, 
а noun is assigned the name that appears to the left of the +. Verbs may 
also be named, but by a different mechanism (described in Chapter 7, “Verb 
Formation”). 

A name must start with a letter of the alphabet; subsequent characters in & 
name may be letters or numerals. The symbols A and 4 are both permitted 
in names in the same way as letters. A name may not contain more than 
TI characters, 


The symbols a (alpha) and w (omega) may also be used as names, but only 
when used alone, and not as рай of a longer name. There are no rules 
regarding the uses to which you put the names a and w, but by convention 
a is used as a generic name for a verb's left argument, w for a verb's right 
argument. 


Since the arbitrary name assigned to a noun is a shorthand reference to tho 
noun, the name serves аз а pronoun. 


APL systems have little that corresponds to the declarations of other lan- 

guages. You do not have to declare the type of noun to which а name 

will refer, or its size. When you use а name, the interpreter simply notes 
% For sample, in languages such as C or Fortran, whan you write а program you bave to mll tw compiler in mêvane 

ю 

ома 


and tbe type and mak of each. They also requi (explicitly or ben) the 
SUS e e ТЫ eee 
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the use made of it. The value to which a pronoun refers may be reassi, 

at any time. Reassignment may change its type, rank, or shape, as well 
its value. 

The only form of declaration is localization of a name to the definition of 
a verb. Names that are local to tho definition of а verb musi bo declantd 
as part of the verb's definition. | 


Indexed Assignment 


The name to the left of the + may be modified by index brackets, in 
expression of the form: 
x[i] + b 
The effect is to produce а new version of x in which the items at position 
1 are taken from b, while the others are retained unchanged from x 
indexed assignment is also discussed as part of the description of index: 
selection in Chapter 5, “Verbs”, 
Indexed assignment requires that: 
• The array x must already exist. i 
+ The expression within brackets must be appropriate to the rank of x 
(that is, must have the right number of semicolons: 1 0). 
* The values of the indexes [1] must be valid, given the index origin 
and the shape of x. 
* The shape of b must match the shape implied by the index expressi 
within the brackets. рыя) bes singin бтн, la which ones E la inet 
at all the locations indicated. 


x and b must be of the same type (numeric, character, or box). 


The Result of Assignment 


When a verb occurs to the left of an assignment, —— 
result of the assignment. The result of assignment is the noun to the right. 
ol the ~. For example, in the sentence 

3xx«analyze data 


the right argument of x is the result of analyze data. Such a sentere 
can be read, “Three times x, which is analyze data.” 
* In “A Dictionary of APL”, this is achieved by b H (OU which bas the advantage that the resuk is the entire modified 
тву x, wheres the formal resuk of х{ i}+b is b. 
Ы ‘The interpreter also tolerates а mismatch between the ranks of b and x, but only when the eddisional axes are of length 
1. 
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This is equally truc for indexed assignment. In the sentence 
3xxlilea 
the right argument of x is the value of a (and not the value of x). 


Multiple Assignment 
А sentence may contain several assignments in а row. For example, 
хеуе2011+а 


assigns the value of а to the name x and also to the name у. It also replaces 
the value of the tub - array z C11. This does not make x and y synonyms; in 
particular, if you subsequently change the value of x, the value of y does 
not change. 


Sentences Producing No Display 


The interpreter displays the result of every sentence except a branch, an 
‘assignment, or one containing а root verb that does not retum а result. 


An assignment sentence is a sentence that has + at the root. In an assignment 
sentence, the name to the left of the copula is assigned to the noun to the 
tight, but there is no display. 


Placing + or De to the left of the principal assignment permits the same 
sentence to assign а namo and display its value: 


х*(\5)*.=15 


I 
° 
° 
0 
1 
0 


oocom 
eeovo 
ooroo 
"oooc 


۰ " " Я 24 
M .. verb am erer 
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Other Mechanisms that Produce Named Objects 
As discussed in the first part of this chapter, the copula + assigns the 
= its lef to the object at its right, Other mechaniams that may also 
a named object are the following: 


[1724 
3 Dfa 


V-editor 


)сору 
)рсору 


Dpdef 
Црраеѓ 


Аз a side-effect, these system verbs create а verb from а 
argument that includes both the verb's definition and its 

‘The verb thus created becomes the local use of the name. 
Chapter 7, “Verb Formation” and Chapter 11, "System Nouns 
and Verbs) 

The ¥-editor (invoked by the symbol V) creates a verb (br 
modifies an existing verb). The name of the verb appears in 
the top (header) line of the definition in the same manner as 
for Ofx or Осг. The verb thus created becomes the global 
use of the name. (See Chapter 7, Verb Formation”.) 


‘These system commands copy into the active workspace some 
ос all of the names in the specified workspace and the objects 
1o which the names refer. The objects thus defined become 
the global uses of the names. (See Chapter 12, “System Com- 
mand 

‘This system verb materializes in the workspace nouns or verbs 
stored in a package. The objects thus materialized become the 
local uses of the names, (See Chapter 11, “System Nouns ahd 
Verbs") 


4-6 Naming Nouns and Verba February 1993 


5 Verbs 


This chapter describes each of the primitive verbs of APL, together wilh а 
few examples to illustrate its use. It also describes the indexing primitives. 
It includes every verb denoted by an APL symbol. However, this chapter 
does not include the system verbs, which are denoted by a distinguished 
пате beginning with U (such as Dread). System verbs are described in 
Chapter 11, “System Nouns and Verbs”. 
There is no inherent order for the symbols; they are arranged rather ar- 
bitrarily. The familiar + - x + come first. After that, symbols that are 
similar in appearance are grouped together, so that Ш comes next to +; * 
© О are adjacent; and so on. 
Names are given with the descriptions. Note, however, that a symbol may 
be associated with several names. (That is why they are not in alphabetical 
order of their names.) The descriptions may distinguish between: 

« a name for the verb's symbol 

. a name for the dyad; that is, the case when the verb ia used with an 

argument on cither side 
. a name for the monad; that is, the case when the verb is used with a 
single argument. 

The variety of names reflect the wide variety of names in common use. 
“A Dictionary of APL” proposes short names borrowed from a variety 
of English contexts. In some cases, those are included here, along with 
allematives used in programming or mathematics. 


In chemistry, the terms monad and dyad refer to objects having valence 1 
and valence 2 respectively. That is how they аге used here. Thus, the dyad 
+ is divide (as in atb), while the monad + is reciprocal (as in +x). 
In the descriptions, the following symbols appear: 

a The verb's left argument. 

w The verb’s right argument. 


Default Argument Ranks 


А verb's rank is the number of axes in each argument cell. 
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Whenever you apply a verb to an argument of rank greater than the 

for which the verb is defined, the “extra” axes are treated as frame axei 
The verb is applied independently to each cell within that frame. The rank 
conjunction * (see Chapter 6, “Adverbs and Conjunctions”) can impose on 
any verb the specific argument rank specified by the noun to the right of v. 
In principle, every verb has a default argument rank. When you use the 
without explicitly saying what argument rank you want, APL assumes 
mean the default argument rank. The default argument ranks are shown 
with the description of each verb. They sre also summarized in Figure 
5-1. 


Argument rank is shown here (and in the argument of the rank conjunctidn 
5) as a three-item list of integers. The items are: i 
* Monadic rank. Rank of an argument сей when the verb is used with 
one argument. 
* Left dyadic rank. Rank of a left argument cell when the verb is used 
with two arguments, 
* Right dyadic rank, Rank of a right argument cell when the verb is 
used with two arguments. 


Agreement | 


The arguments of a dyad must have frames whose shapes agree. The two 
frames agres when: 


. they have the same shape; that i, the same mumber of axes and the 

same length along cach axis 

or 

. one frame is empty; that is, has no axes. 

When а frame is empty, the argument consists of a single cell. When one 
argument has an empty frame but the other does not, the frame that is 
empty establishes the frame for the result. The single cell from the empty 
frame is paired with each of the cells in the other argument. 


Scalar Verbs 


In mathematics, a scalar is an object that has no axes (in this тапш}, 
usually called an item). A scalar verb is onc that is rank-O and return a 
rank-Ü result. 


| 
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Because а scalar verb is defined without reference to axes, when you apply 
it to an array argument, ай the argument’s axes are frame axes. Therefore, 
the verb applies independently to each of the items throughout the frame. 
When a scalar verb is used dyadically, the usual rules apply: either the 
two frames must have the same shape or one of them must contain only 
a single item, to be paired with every cell in the other argument. For 
example, adding the numbers contained in frames of length 3 produces 
three independent additions of the corresponding cells: 


1237 12 5 20 
13 7 23 


That is because 1+12 i$ 13, 245 is 7, and 3420 is 23. 


Extending the Empty Frame 


"When one frame is empty, the single cell corresponding to that empty frame 
is paired with each cell in the other argument; the empty frame is said to 
be extended to match the frame of the other argument. The result frame 
has the same shape as the non-empty argument frame. This extension is 
illustrated in the following examples for addition: 


111 + 4.9 70.012 34 
115.9 110.988 145 


4.9 70,012 34 * 111 
115.9 110.988 145 


Unbounded Rank 


А verb may have unbounded rank (sometimes called infinite rank). When 
a verb has unbounded rank, no matter how many axes the argument has, 
they are all treated аз part of а single cell. In the descriptions that follow, 
unbounded default rank is denoted by the oo symbol. 


Unspecified Rank 


For some verbs, no default argument rank has yet been specified. (The 
fact that some argument ranks remain unspecified is not а feature of the 
language, but a limitation of the current implementation.) You can still 
use the rank conjunction 9 to specify a verb's argument ranks, or you can 
supply an argument of the usual rank. But if you apply such a verb to an 
argument that has more axes than the “usual” case, APL, does not know 
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how to partition the axes into frame and cell. И reports a rank error. 
The verbs in Figure 5-1 whose entries contain an asterisk () are those for 
which a default rank has not yet been specified. 


Reduction and Identity Elements 


The class of derived verbs called reductions (see Chapter 6, “Adverbs 
Conjunctions”) applies the same verb between cach of the major cells 
its argument. For example, if an array X consists of three major cells А, 
Xa, and Xs, then the F reduction of X, written fx. is computed by: 


xi f * F *. 


A reduction applies to as many cells as the argument has; the expressipn 
+x computes the sum of two cells when X has two cells, the sum of three. 
cells when X has three cells, and so on. i 


The verb used in a reduction is a dyad. Reduction is valid even when 
argument consists of only one cell, or zero cells. What does it mean to 
apply а dyad to one cell, or to no cells? Ordinarily, "the sum of onc ? 
might seem nonsensical, and "the sum of no things" even more во. A use! 
generalization is obtained by the following rules: 


. When w contains only one major cell, the result of any reduction is w. 


» When w contains no major cells, the result of any reduction of w is the 
verb's identity element. 


‘The reason for this becomes apparent when you consider how а final res 
is constructed from a set of partial results. It is often useful to partiti 
а task; that is, to perform the task for part of the data, then another 
and so on. A final step consolidates the results from the parts. Partition 
is possible when a simple rule relates the result obtained from the varidus 
partitions to the result for the array as a whole. For example, if an array 
has five cells, you could sum the first two cells, then the last three, and 
finally sum those results to get the overall sum. 


(Sum of all five) = ( Sum of first two) + (Sum of last three ) 
( Sum of ali five ) = ( Sum of first three ) + ( Sum of last two ) 


... and so on. Al 
More generally, you should be able to split the five cells anywhere; sum- 
ming the separate partitions and then summing the results should still give 
you the same result in the end. This principle helps define what reduction 
should mean when it is applied to one cell, or no cells. Generalizing from 
the preceding equation, we get the following: 
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Moued| 5574 Mouad Dyad 

Verb | Rank İL Rank | R Rank Rank | L Rank | R Rank 

+ 0 | ° 0 Unk&ed| 0 0 

- 0 0 0 Undefined. 0 0 

х 0 0 0 Undefined ° 

* 0 0 0 дымы | 0 0 

LI 2 LJ 2 LJ o о 

* 0 0 0 о © ә 

е 0 0 0 Undefined. LJ 

o ° ° ° Undefined | оо © 

r 0 0 0 © . . 

L 0 0 9 Ф Undefined | Undotined 

[ 0 0 0 00 © © 

1 0 0 0 о o oo 

? 0 . . . » . 

> E В a E P E 

< оо 0 0 0 * * 

> 0 0 0 Unsied| * ad 

х Use] 0 0 о * * 

2 [Uma] 0 0 9o LI ә 

= [Uwe | 0 0 о © ә 

# LJ 0 9 LJ м Е 

= ‘Undefined oo o ‘Undefined 0 о 

* 0 ‘Unde fined Undefined Undefined. во o 

I | Undefined — Undefined x * * _| 


Undefined: No meaning established for this verb form. 


^ This verb form bas meaning, but no default argument rank has been specified for it. 
Figure 5-1 : Default argument ranks of primitive verbs. 
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(Sum of all five ) = ( Sum of first опе ) + (Sum of last four) 
(Sum of all five ) = (Sum of first none ) + (Sum of last five ) 


Tt becomes evident that “the sum of the first one cell” should be the first cell 
itself. The sum of no cells should be something that makes no difference, 
since "sum of the last five" already gives the result “sum of all five. 


For a particular dyad, the identity element is the value which, when it is 
one of the verb's arguments, guarantees that the verb's result is equal to the 
other argument. 0 is the identity element for addition because O+anything 
gives you anything, unchanged. Similarly, 1 is the identity clement for 
multiplication, because 1xanything gives you anything, unchanged. 


For some verbs, there is no identity element. For others, there is a right 
identity but not a left. For example, anything+1 gives you anything, but 
that is not true for 1+anything. 


In the individual descriptions that follow, the value of а verb's identity 
element is noted where it has one. The identity elements are summarized 
in Figure 5—2. (See also the discussion of the 2 and / adverbs in Chapter 
6, “Adverbs and Conjunctions".) 


Smallest representable number 
71.2370055773322621е75 


Largest representable number 
7.2370055773322621е75 


x 
* 
E] 
< 
> 
2 
5 
* 


Figure 5-2 : Identity elements for scalar dyads. 
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Result Rank and Shape 


For many verbs, а result cell has the same rank and shape аз its argument. 
cells. Wherever the rank or shape of a result cell is different from the rank. 
or shape of the argument cells, the description notes that fact. 
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Verb Definitions 


+ x + 
Plus, Minus, Times, Divide 


These four dyads are familiar from elementary arithmetic. The monads are 
also defined, and given names as follows: 


Identity | Argument 


Monad Dyad | Element | Rank 
+ | Conjugate Plus 0 0 
- | Minus; Negate | Minus 0 0 
x | Signum Times 1 0 
+ | Reciprocal Divide 1 0 
Dyads + - x + 


The dyadic meanings are those of arithmetic. 


For complex arguments, the usual rules apply. That is, the sum (or differ- 
ence) of a pair of complex numbers is the sum (or difference) of their real 
and imaginary parts considered separately: 


214 + 1.572.1 
3.516.1 


The fact that the sum of two complex numbers is represented by the кит of 
their real and complex coordinates taken separately is something you can 
exploit in graphics applications. Using complex numbers to describe a set 
of points in а plane, you can compute a linear translation of a set of points 
simply by using + to add the amount of change in the two axes. 


Cartesian Representation of Complex Product 


The product of a pair of complex numbers can be stated in terms of орег- 
ations on their Cartesian representations. Suppose a verb Ct decomposes 
а complex number into its real and complex parts, and the inverse Cx re- 
constructs а complex value from such a representation. Then the product 
of two complex numbers a and ш is given by the following definition of 
Times: ' 


called direct . definition takes a single line. The 
ft argumant is represented by à. and its right mrumen by м. The rn 
imu. For mere detailed treatment of this form of definition, see “A Ba of АРЫЛ 
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Times: Cx (-/axw) ,V0 (+/axdw) et, a 4 WeCt w 

си 9 110100 

сх: +/ 79 7110%1 w 
The complex value is the real part plus 1 times the complex рай, where 
4*7140.5. The expression +/79 110 achieves that because 790w is 
defined to be w, while 11000 is defined to be 1 times v.) 


Polar Representation of Complex Product 


The product can also be computed when each complex number is repre- 
sented by its magnitude and phase angle. In that case, the product of two 
of them has: 
e magnitude equal to the product of their magnitudes 
* phase equal to the sum of their phases. 
Suppose that a verb MP decomposes a complex number into its magnitude 
and phase angle, and the inverse CMP reconstructs a complex value from 
such a representation. Then the product of two complex numbers a and w 
is given by the definition of Times: 
Times: CMP (1 0/axw), 0 1/atw + GeMP а 4 GMP ш 
MP: ® 10 12 ow 
СМР: х/ 710 12091 ө 


Rotation of a set of points in the complex plane through an angle of $ radians 
is equivalent to multiplying by а number having magnitude 1 and phase 
4; you can exploit this identity in graphics applications that use complex 
numbers to describe a set of points in a plane. 


Division by Zero 


As in arithmetic, dividing a non-zero quantity by zero is undefined and 
the interpreter rejects it as a domain error. However, to preserve some 
convenient identities, APL defines 0+0 to be 1.* 


Monad + 
+w gives the conjugate of w, also called the complex conjugate. Formally: 


нә сә (luxu) When «#0 
жо «= 0 When = 


. 
-301). However, фе convention that 0+0 is 1 was adopted by all early implementations of APL, and is 
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‘The conjugate is the value you get when you reflect the argument around 
the real axis. The real part is unchanged, but the sign of the imaginary part 
is reversed. For example: 


49 793 7732 8773 273 
9 773 77372 B93 7253 
Thus, +w differs from w only when tis complex. 


Monad – 
‘The result haa the same magnitude as the argument, but opposite sign. For 
a complex argument, the result reverses the signs of both the real and the 
imaginary part. 

Monad x 


xw gives the trend of w. For real arguments, that is equivalent to the signum; 
the result is: 


1 where w is positive; 
0 where w is 0; 
71 where wis negative. 


Formally, the trend is defined by: 


Kw h When wo 
x» ж» 0 When = 


For a complex argument, the result is the point at which a ray from the 
origin to « intersects the unit circle. 
The trend is not affected by Oct, comparison tolerance. See the definition 
of equal (z) for a definition of tolerant comparison. 

Monad * 


4w is defined as 144, that is, as reciprocal. As in arithmetic, reciprocal is 
undefined when the argument is 0, so you get a domain error. 
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Matrix Inverse; Matrix Divide 


The @ verb domino is a generalization of the mathematical function matrix 
inverse. Mathematicians have no special symbol for matrix inverse, but 
indicate it by writing M-!. Matrix inverse is analogous to the reciprocal 
because, just as (for a non-zero number n) 

1 e» (en) хл 
for a non-singular matrix 4 

I e» (N+. XH 
where Iis the identity matrix (a square matrix having the same number of 
columns as M, with ones along the diagonal and zeros elsewhere) and +. х 
is the matrix dot-product, an analog of multiplication for matrices. 
Just as not all numbers have а reciprocal (zero has no reciprocal}, not 
all matrices have inverses. Matrices with no inverse are calied singular 
matrices. 
Continuing the analogy with division of numbers, matrix division satisfies 
the identity (for two appropriately shaped matrices A and M, and N not 


singular). 
a e» (anxn (Numbers) 
А c» (АШМ)+.хМ (Matrices) 


If you attempt to use a singular matrix as the right argument to В, APL 
rejects the expression as & domain error. 
Monad 8 


The inverse of а non-singular matrix M is found by BM. The monadic use 
м is equivalent to IX. The shape of each result cell is the reverse of the 
shape of an argument cell. 


Dyad @ 
In general, the matrix quotient айо is linked to the inverse of a matrix by 
the identity: 
‘See the discussion of inner product in the section on tha dot (.) conjunction in Chapter 6, “Adverbs and Conjunctiona". 
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$-12 Verbs 


аво + (#)+.ха 
When w is square (that is, has as many rows as columns), the solution is 
exact. When w has more rows than columns, the result is the least-squares 
approximation that minimizes the sums (down the columns) of the squares 
of the difference between a and оњ. хаво. 


For a matrix M and columr-vector (that is, a one-column matrix) c having 
the same number of rows as M, 


сач 
is the solution to a set of linear equations: 


c The constant terms. 
M A matrix containing the coefficients for each of the unknowns. 


M has a column for each unknown, and a row for each equation. Since you 
must have af least as many equations as unknowns, M must have at least as 
many rows as it has columns. When M is square, and has the same number 
of rows ма c, then: 


C WR M +.х cf 


When M has more rows than columns (and there is a row of М for each 
major cell of c) then ch is the least-squares approximation, defined to 
minimize each of the column-sums 


rcd deco Mt. Ac 


where d is the difference between c and M+. хсйїм. When the solutions are 
real, dx+d is equivalent to 2. 


APL treats a rank-1 lefi argument as if it were а one-column matrix. (See 
the discussion of “Frame and Cells with Dyad ii", below.) 


Example: Multiple linear regression requires a list of dependent obser- 
vations in the column-vector c and a matrix of independent or predictor 
observations p. The matrix p has а column for each of the independent 
variables and а row for cach row of c. (Since APL accepts a list in the 
place of а column vector, that may be an item of c for cach row of p.) 
The coefficients of the best-fitting linear combination of the independent 
variables are obtained from clip. 


Example: Finding a best-ftting polynomial is essentially the same proce- 
dure bot with a single independent variable. The columns consist of the list 
of observations of that variable, cach raised to the successive powers by an 
expression. Hence, to find the coefficients of the best-fitting polynomial of 
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degree d to approximate the observations a from a predictor variable p, the 
expression is: * 
а p- 40%, 1d 


"When a has multiple columns, the result is a matrix containing in each of 
its columns an independent solution for each of the columns of a. 


Frame and Cells with Dyad iB 


‘The left argument of matrix division has unbounded rank. That is, the left 
argument is treated as a single cell, regardless of the number of axes. The 
right argument rank is 2. Thus, when the right argument has more than two 
axes, any additional axes constitute the frame in which the rank-2 cells are 
embedded. Each of the «cells is paired with the single cell formed by the 
entire a. 

The length of the first axis of а must match the length of the first axis of 
each ell. Those matching axes disappear from the result, as they do in 
reductions. The remaining axes of а after the first — call them o's trailing 
axes – contain the constant terms for independent seis of equations to be 
solved, each set in a column of a. There is a result vector corresponding 
to each of a's column vectors. 


‘The various columns of d do not interact. Suppose cach of the w-cells has 
r rows. Then the бги axis of a must have length r to match. Each of 
the columns of a, however arranged, contains а separate set of constants 
for which a separate solution will be found. For example, if there are six 
such columns, И makes no difference to the calculation whether they are 
arranged so that a has shape (г, 6), or (r, 6 1), or (r, 2 3), or 
(г, 3 2), and зо оп, The manner in which the axes of the arguments а 
and ш contribute to the axes of the result are summarized in Figure 5-3, 


‘with the high-order terza fest aad the constant Inet, tbe ardar may be. 
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Resul poem a} 


Figure 5—3 : Shape of the argument and result of dyad B. 


* @ 
Power, Log 


Identity | Argument 
Monad Dyad Element | Rank 


* | Exponential | Power, 000 


e | Natural log | Log base-a 000 


Monads х and e 


The exponential denoted by +w is equivalent to e-, where € is the base of 
the natural logarithms, given approximately by: 


*l 
2.718281828 


The natural logarithm @ is inverse to * in the sense that 
ш ж» Oro c x99 
Moreover, if e is e, the base of the natural logarithms e+*1, 


w c cow. 
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For both real and complex arguments (except when w is 0), the log of w is 
equal to the log of the absolute value of w plus 1 times the phase of ©; that 
is: 

ew c (elw) + 0j1x120w 


However, for a positive real argument, 0j1x120w is zero, and so has no 
effect on the result. For a negative real argument, the imaginary part of the 
result is я radians. That is because the log is equal to the arc of w, and the 
arc of any negative number is я radians. @0 is undefined and results in a 
domain error. 


92 3,(*2), 1 
0.6931471806 1.098612289 2 0 


*22P - 1,(*1),2,(*2) 
033.141592654 1]3.141592654 
0.693147180673.141592654 273.141592654 


60. 5 0.6 
0. 6831471806 0. 5108256239 


Dyad * 


The expression a4 is often read as “а to the power w.” ak2 and a and 


40.5 am respectively the square, cube, and square root of a. The general 
definition of av for real and complex arguments, is: 


сно e waxed When ar 
ааш e 0 When a=0 and w0 
arw c 1 When az0 and w=0 


For the simple case of a non-negative integer right argument, алш is equiv- 
alent to x/wpa. Since x/ applied to an empty list yields 1, axọ is 1 for 
any a, even when a is zero. 


Raising a number to a fractional power is equivalent to extracting a roof; 
for instance, the three-fifths root of a can be written а*3+5 or the square 
root of а as аж+2. 


When a is negative and w is fractional, the result is complex. Multiple 
roots may exist, some real and some complex. The result is the first root 
(proceeding counterclockwise from the positive real axis), regardless of 
whether it lies on the real axis. For odd integral roots, this result may 
sometimes be surprising. For example, although 72 is a cube root of 78, 
it is not the principal root by the rule just stated: 


February 1993 Verbs 5-15 


SHARP APL Reference Manual 


284.3 
171.732050807568877 
131.732050807568877 2 *3 


Dyad e 


5-16 Verbs 


The base-b logarithm bew is inverse to power in the sense that: 
ш e bebew t babe 


The dyadic logarithm ce is equivalent to the ratio of the logs of the 
arguments considered separately; that is: 


asw « (eu) ten 
Since the logarithm of 1 to any base is 0, 1€ is normally а domain 


error and del is normally 0. But 1e1 is 1 since in APL 0+0 is defined 
to be 1. If either of а or ix negative, the logarithm may be complex: 


we 4% 2 2 10,01 
1 0.046427) 0.21039 0,076663j 0.34746 
174.5324 1 1.6515 
0.6055172.7444 0.60551 a 
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Circle Verbs 


Monad o 


The expression ow is equivalent to times w, where X is the ratio of the 
circumference of a circle to its diameter, approximately: 


3414615926535 


Dyad о 


о1 


In the expression аош, the left argument а must be an integer from the set 
712 through 12, inclusive. The value of a selects one of the families of 
circular verbs, as follows. 


12 


3 


EE 


5 6 7 
75 7677 


Circular or trigonometric (argument in radians) 
Inverse circular or trigonometric (result in radians) 
Hyperbolic 

Inverse hyperbolic 
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Selection of Function by Left Argument of o 


оош (1 o. 5 


10и sinw 
созш 
tan w 


( I 2) 0.8 
arsinh w 
arcosh w 
айапһ w 


(1404294065 
sinh w 
cosh w 
tanh w 


(71-0ж2)%0.5 -(71-0ж2)#0.5 


Real part: (wHw)+2 
100 | Magnitude: |w 

110w | Imaginary: (w-+w) +02 
Phase angle: 11090 


Identity 
71000 | ж 

07 
*0J1xu 


Geometric View of the Pythagorean and Circular Functions 


The various circle verbs can be represented by constructions on а unit circle. 
whose origin is О (see Figure 5—4). The distance OP is 1. The angle a 
establishes the point P al which a ray through the origin cuts the unit circle. 
For the angle a, the altitude PR represents the sine of a, OR the cosine of 
a, and PT the tangent of a. 
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PR sine a 
ОР 1 OR cosine 
PR = 0008 | PT tangent a 
OR 0ОРК PS cotangent a 
ОТ = ФОРТ OT secant a 
РТ 400T | OS cosecant a 


Figure 5-4: Pythagorean and circular verbs in terms of the unit circle. 


The inverse functions 10 and 20 have domains restricted to values whose 
magnitude docs not exceed 1, Since sine and cosine are cyclic, a given sine 
or cosine is related to any of an infinite number of arcs, differing from cach 
other by successive multiples of 27. For a given sine, 10 retums the arc 
lying at or between the range – and f radians. 


Geometric View of the Hyperbolic Functions 


Figure 5-Sextends the geometric constructions shown in the preceding 
figure. Here again О marks the origin, the center of a unit circle, so that 
the distance OP is 1. The two arms of the unit hyperbole are shown tangent 
to the unit circle, with the major axis of the hyperbola along the horizontal 
axis of the figure. As before, the line SPT is tangent to the unit circle. 


The hyperbolic cosine relates the coordinates of а point on the unit hyper- 
bola to the sum of the Iwo areas (shaded in Figure 5—5) each bounded by 
the following three curves: 


A line from the origin to that point. 
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. The unit hyperbola itself. 


The major axis of ће unit hyperbola. In the figure, O is such a 
point. If (as shown here) the unit hyperbola is oriented so that 
its major axis lies horizontally, the hyperbolic sine is the vertical 
distance from the origin to O (equal to TO). The hyperbolic cosine 
às the horizontal distance 07. The hyperbolic tangent (by analogy 
with the circular tangent) is the ratio of the hyperbolic sine to the 
hyperbolic cosine. 


Figure 5—5 : Hyperbolic verbs in terms of the unit hyperbola. 
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10a hyperbolic sine 
20a hyperbolic cosine 
30a hyperbolic tangent 
05 = +10а hyperbolic cosecant. 
OT = «20a hyperbolic secant 
PS = 430a hyperbolic cotangent 
70 jan" 


The inverse hyperbolic functions are arsinh, arcosh, and artanh. The "ar" 
prefix indicates “area” (whereas the prefix "arc" used with the inverse cir- 
cular functions indicates "arc"). 

‘The inverse hyperbolic functions give you twice the area of the hyperbolic 
sector described by the corresponding sinh, cosh, or tank. If x is а value 
of the hyperbolic tine and y is the value of the corresponding hyperbolic 
cosine, and z is their ratio, then the area enclosed is equal to: 


Sox which equals “60y which equals ~70z 
‘The result retumed for the area of the hyperbolic sine and cosine has the 
same sign as its argument Since in principle sink and cosh can take on 
any values, both the domain and the range of arsinh and arcosh are infinite. 
Since sink must always be less than the corresponding value of cosh, tanh 
has a magnitude that approaches but can never reach 1. 
In practice, the areas of the hyperbolic functions are evaluated by exploiting 
the following identities: 

7500 4 ewt {0% 

7600 «9 Өш س40‎ 

“Tow e 0.5xe(140)(1-9) 
This method of computation gives 750 and 760 an effective domain of 
all numbers whose magnitude is less than about 1057; the results have 


magnitudes less than about 85. The artank function 770 has an effective 
domain of numbers whose magnitude is leas than about 18. 


Representations of Complex Numbers 


A complex number may be resolved to its real and imaginary parts by the 
expression 9 11 *.O w; for example: 


9 11*.0374 
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От, it тау be resolved into its magnitude and phase by 10 12. 0 for 
example: 


10 12*.037j4 

5 0.927295218 

You get the inverse transformations by exploiting the identities: 
ш e» 79 7114.0 9112.05 
w e 710 12 .; 10 12 *.0 w 


(Sec also the discussion of complex arguments accompanying the descrip- 
tions of + * +.) 


TL 
Floor, Ceiling; Max, Min 


Monads L and f 


The expression Lw retums the floor or integer part of w. When w is an 
integer, the result is о; but when w has a fractional part, the result is the 
first integer that is smaller than w. Stating it the other way, Luw is the largest 
integer thal is not greater than w. 


13.10 76.7 79 
307779 


The expression [w retums the ceiling of w. When wis an integer, the result 
is û; but when w has a fractional part, the result is the next larger integer. 
Thus, [u is the smallest integer that is not smaller than w. 


[3.10 76.7 79 
407679 
Га can be defined in terms of Lw thus: 


[ш e» 17-0 €» 1-0 


$-22 Verbs February 1993 


SHARP APL Reference Manual 


Tolerant Floor and Ceiling 
‘The implied comparison of w with the integers is tolerant, When w is 
sufficiently close to an integer, both [w and Lw are ш. “Sufficiently close” 
is defined in terms of the visible value of the system variable Oct. The 
formal definitions of floor and ceiling are:* 


floors n-(Dctxif lw)<((ne(xw)xL0. 5+1) 0 


ceiling: -floor-w 


‘Thus, if x is any integersOct, the ceiling of x is that integer, even though 
in that case [ x is (strictly speaking) smaller than x. 


The default value of Oct is 1.4196976927394189e 14. 


Floor of a Complex Number 


You can represent a complex number as a geometrical point in the complex 
plane: a plane in which displacement along the x-axis represents the real 
portion and displacement along the y-axis represents the imaginary portion 
of a number. The floor of a complex number lies at a point on the inter- 
section of lines for real and imaginary integers; that is, both its real and 
its imaginary parts are integers. You can think of the process of finding 
the floor as motion from a point anywhere in the complex plane to a point 
at one of the vertices of the surrounding square bounded by the real and 
imaginary integer lines (sec Figure 5-6). 

The vertex chosen is one that satisfies the constraint that the distance be- 
tween a number and its floor is always less than 1. Thus, there is а zone 
in each square for which the floor is not what you would get by taking 
the floors of the real and imaginary parts separately. The algorithm by 
which APL finds the floor of & complex number is the one proposed by 
McDonnell in 1973." Imagine a grid of integer lines on the complex plane. 
The task is to map a point anywhere in the plane to one of the lattice points 
on the grid — that is, to a point whose coordinates are described by a real 
integer and an imaginary integer. The floor f of a complex number w is 
found by the following algorithm. 


«© Let LL be the point at the lower left comer of the unit square containing 
ө. 


Thasa were derived by Robert Bernecky eod DL. Fockes in 1978. See SHARP APL Technical Мом 23: Comparison 
) 2 7 


| 300000 sei 79 “114.019 paai 0 


Eugens E. McDonnell, members: applic 

\ Nor 320-3015, 1973. — шг [Жегу L cher F, аш бек. АР АН. Congress IS. 
North Holland Publishing, 1973. 
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e Let fr and fi be the fractional parts of the real and imaginary parts 


of w. 


Then, 


When 1»frefi: f- LL 


When (1&fr*f1) and frefi: f- 
When (1sfr*fi) and fr«fi: f 


Those rules can be stated as APL direct definitions in which | and | are 
applied only to real arguments: 


floor: 

LL: 
casei: 
case21 
casei: 


(LL w) + ((casel w),(case2 w),case3 w)/0 071 1 
(Lreal w) + 0jixlimag w 

pr w)+ft w 

(Is(Fr ff ^ (fr w)< fiw 
(1506г f w) ^ Cfr wz fia 
llreal w 
11 imag w 
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In Figure 5-6, a unit square is divided by its diagonals into four zones. A 
point in Zone 1 or Zone 2 is mapped to LL; a point in Zone 3 10 1148071, 
and a point in Zone 4 to LL*1. 


‘The zone of all points in the plane that are mapped to particular complex 
integer is thus a rectangle tilted at 45°, with the floor at the center of its 
lower edge. Figure 5-7 shows a portion of the complex plane tiled by such 
rectangles. 


Figure 5-7: The complex plane tiled by areas having equal floors. 


Dyads L and г 
alw retums the minimum of а and c (that is, whichever is smaller), and 
а Ге retums the maximum (thal is, whichever is greater). For example: 
344 74 
34 
Maximum and minimum are not tolerant; that is, their results are not subject 


to Oct. These verbs are defined only for real arguments; the system reports 
а domain error when an argument is complex or non-numeric. 


February 1993 Verbs 5-25 


SHARP APL Reference Manual 


When the reduction adverb ^ modifies Г, the result is the maximum of the 
major cells of w. For example, if the shape of xis 3 4 5, then 


[#х €» х([1;}] F x(21:31 x3: 


When the first axis of w has length zero, the result is the identity element 
for maximum. That is the number compared to which all other numbers 
are bigger: minus infinity. In practice, the APL system retums the smallest 
representable value. The actual value depends on the particular system. In 
APL, it is approximately equal to -7.237x 10". 


For the same reason, the identity element for L is positive infinity, and the 
system retums the largest number it can represent. Here too, the actual value 
depends on the particular system. In APL, it is approximately 7.237x 10", 


Magnitude; Residue 


Identity | Argument 
Dyad Element | Rant 
Magnitude; | Residue 
Absolute value 


Monad | 


Dyad | 


The definition Jw « (x4) 0, 5 yields the magnitude or absolute value 
of w. This definition applies equally to real and to complex arguments. For 
а complex w, the result is the hypotenuse of a right triangle whose sides 
are the real and imaginary parta of the number. If the real and imaginary 
parts of w are denoted as re and im, then |w is ((re*2)*im2)*0,5. 


A familiar use of residue is to determine the remainder resulting from 
dividing a non-negative inleger by a positive integer. For example: 


The definition a |w «=> @-axLw+a+0=a extends this notion to a zero left 
argument. When o is zero, the result is the right argument unchanged. К 
also extends the verb's domain to fractional right arguments and to negative 
or fractional left arguments. When a is a negative integer, the result ranges 
between а and zero, just as it does when с is positive. For example: 
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T3474 73727101234 
7107271072710 7 

112.5 3.64 2 71.6 
0.5 0.64 0 0.4 


However, for cases such as (+3) |243, in order to produce a true zero 
(rather than a small fraction) the residue is made tolerant in the following 
way. Where а is non-zero, and w is not an integer multiple of a, the residue 
is found by subtracting from w ihe product axs, where 5 is the tolerant 
floor of wra. Stating the same thing more formally: 

Let 5+%+а+а=0 


When (0) АСГ DALS, alw еә w-axLs 
Otherwise, ajw ++ бхй=0 


For example: 


0.12.5 3.64 2 “1,6 
о 0.04 00 


‘Consider the result when the modulus is 3 or ~3 and the right argument is 
10 or 8: 


3 73 e.l 10 78 
11 
72 "2 
Figure 5-8 illustrates the results obtained from the above example. 


The definition of residue applies equally to complex arguments. The ex- 
tension takes advantage of the properties of L (floor) applied to complex 
arguments. As a consequence, the residue of any number (whether real 
ог complex) is always less in magnitude than the modulus (except for the 
special case of zero modulus, when the residue has the same value as the 
right argument). 
For example, when Oct is set to 0, because of imprecisions in the intemal 
representation, the following expression misses certain multiples: 

0. 24 . 3215 -Oct+0 
0. 127 0. 16 0.320. 24 0. 12 0. 16 0. 320.24 0. 127 0. 16 


But with the default value of Det, APL is able (correctly) to detect that 2 
and 4 are multiples of . 24 . 32 and to retum a 0 residue: 
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Figure 5-8 : Schematic representation of 3 31 10 and 3 73178. 


)clear 
clear ws 
0.24370.32 |5 
0. 127 0. 16 0 0. 127 0. 16 0 0. 127 0.16 


Factorial; Combinations 


| 


|' | 


Identity | Argument 
Element | Rank 


S 000 
Monad ! 
When w is a non-negative integer, the factorial is defined by: 
10 4 x/us 


For example, 14 is x/1 2 3 4, or 24, and 10 is 1. 


Monod Dyed 
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For a negative integer, the factorial is undefined. For a real argument other 
than a non-negative integer, Luis closely related to the gamma Г function, 
30 that а value of the gamma function can be obtained from: 


Pw) e 10-1 


Dyad ! 
The dyad atw is defined in terms of the monad thus; 
alw ж» (Iw)eCta)x(to-a) 


For non-negative integer arguments, a tw yields the number of distinct ways 
of selecting a things from w things; this accounts for the name “out of,” 
and for its use in producing binomial coefficients. For example: 


012 3 4:4 
14641 


For a negative integer I. the expression 11 ів not defined, because, near а 
negative integer, the magnitude of 1 I approaches infinity. In the definition 
of agw shown above, these near-infinities may cancel, permitting a 10 to 
be evaluated provided we assume that these infinite values occur in the 
following ways: 
1. When a and w are both non-negative, but a»«, the term wa is infi- 
nite, yielding 0 for the result of a 10. This agrees with the observation 
that there are no ways to pick а things from a smaller collection. 


2. When infinite values occur in both numerator and denominator, they 
are assumed to cancel. This can be seen in the values in the following 


function table: 
13 72 71012 3 
1.11 
1 2 1 9 0 0 0 
0 1 ^71 ° 0 0 0 
0 0 Y 0 0 0 0 
$ 1 1 3 1 Ф: 1 
"UA та UA 0 1 2 3 
6 3 1 0 0 1 3 
710 74 "1 0 0 0 1 
| 
EIE рн л eng Hea g Hahona Peco US Dea ee 
National Bureau of Standards, Applied Mathematics Series 
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The generalized definition adopted for dyad | permits evaluation of the 
Beta function by the identity: 


B(a,0) e +шх(о-1)!а+%-1 


The random verb 7 selects either а tingle number or a set of distinct 
numbers from a population of numbers. For example, each of the following 
selects from the first ten integers: 


710 


3710 
927 


The size of the population from which numbers are selected is determined 
by the value of the right argument. The population is the first w integers; 
that is, a result cell is selected from 1w. The population is therefore affected 
by the value of Dio. 


‘The verb гой is named from the analogy with rolling a die to choose one 
of a set of numbers with equal probability. 


The verb deal is named by analogy with dealing from a pack of cards. The 
result of а?о for each of the corresponding cells of a and w із a list of 
length a in which all the elements arc distinct. 


Argument Rank 


The default rank of dyad 7 is at present undefined; 7 may be used with 
array arguments only by stating its argument rank explicitly. For example, 
to independently generate four random numbers taken from 1100 and also 
four taken from 1200: 


? 
Roll; Deal 
4 
Monad ? 
Dyad ? 
$-30 Verbs 
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4 750 - 100 200 
56 27 84 20 
20 116 133 180 


Pseudo- random Algorithm and Or! 


The results of ? (both monad and dyad) are “pseudo-random.” That is, 
although the results (collectively) satisfy most tests of randomness, they 
are produced by an explicit and repeatable algorithm. The value emmed 
depends on the visible value of the system noun Ur 1 (random link). Bach 
time APL (successfully) executes ?, it sets Ur! to а new value. If, on 
different occasions, you set the same value of Пг1 and then invoke Р on 
the same arguments in the same sequence, you get the same results, (Scc 
the discussion of 02-1 in Chapter 11, “System Nouns and Verbs“) 

The algorithm for generating random numbers is the Linear Congruential 
Method developed by D.H. Lehmer іл 1951.” The algorithm depends on 
two constants: а prime pe2147483647 and a multiplier m«16807. (The 
prime is the largest prime representable with 31 binary digits. The multiplier 
is a primitive root of p that is close to the square root of p; the value 16807 
is 745.) 


When w is an item less than 24, APL finds the value of 70 by 
Pw €» Üiotlexürltp 4 ОгЈерілә0гі 
in which | means the non-tolerant floor (as one would get when Oct is 0). 
For an argument greater than or equal to 201, APL sets Ori twice. If the 
result of the intermediate set is called r1, so that 
Orl+p|mrl+p| mir] 
the formula becomes 
Фә €» ШШонх((г19]г1х2#32)+1648)+71+2%31 


Random numbers generated in this fashion are rectangularly (or i- 
formly") distributed; you can get other distributions by applying various 
transformations to the rectangular values that ? generales, For example, 
random normal deviates with mean=0 and o- may be obtained by: 


normal: (1002xuni form w)x( 2xeuniform «)*0.5 
uniform: (?99m-1)*m«2147483647 -Qio«l 


APL evaluates а?а using repeated calls to a short cut version of the mecha- 
nism for monad ?. In principle, the method is to generate random integers, 


* Sea DE Kouh, The Art of Computer Programming ~ Semisamarical Algorithms, Vol. 2, Addison-Wesley, 1969, 
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< > >р 


keeping those that fall within the range specified by а and discarding those 
that do not. However, the result of dyad 7 is not necessarily what you 
would get by using monad ? and discarding out-of-range items from the 
result 


Box, Open; Link 


Identity | Argument 

Monad Dyed Element | Rank 

< | Box; Enclose [see Less] [none] o 00 
> | Open; Disclose | (see Greater] | [none] | 0 0 0 
> | Conditional box | Link [none] | oo оо co 


The monads < and > form a box and open a box, respectively. (The dyads 
« and > are the relations less and greater, discussed in the next section.) 


A box is an item (or scalar). It has no axes. However, it may contain an 
array of any type, rank, or shape. A box is thus a scalar encoding of an 
array. 

Because а box is an item, within an array of boxes each individual box 
occupies a single position, just as а number occupies a single position in a 
numeric array, or a character in an array of characters. An array of boxes 
thus permits you to handle nouns of arbitrary rank and shape within the 
same simple rectangular framework used for numbers or characters. 


Boxing an array always produces а result that is an ilem and always in- 
creases by 1 the number of times it will be necessary to open the item 
1o retrieve ils unboxed contents. This is made obvious when you set Ops 
жо that the boundaries of а box are shown explicitly in its display. For 
example: 


Dps+0 0 72 72 

кх+126 
126 Open йет 

<х „one level of boxing 
tall 
11261 
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««x ^Two levels of boxing 


Ши 
112611 
fit 


— 

Thus, when the argument w is already an item, <w boxes it again and 
produces a result with an additional level of boxing; < is never identical 
10 ало Thus, an open item (that is, a number or character) is not equal to 
any boxed item, not even to the same item enclosed in a box: 


2 * <2 


Monad > 


The monad > is the inverse of <: it opens a box, to disclose what lies 
within. When is an item, >w retums the array that was boxed to produce 
ө, 


When the argument wis already open, the result is the same as the argument. 


An altempt to open amays containing mixed character and numeric data 
resulu in a domain error. 


Since > has argument-rank 0, all the axes of w arc frame axes. Thus, the 
result retumed by >w has the same axes as w, followed by the axes of 
the arrays disclosed from the various boxes. When ail the boxes contain 
cells of the same rank and shape, the cell axes retumed by >w are the axes 
common to all of them. For example, when is a 5-by-2 table of boxes 
and each box contains а 3-by-4-by-7 array, then the shape of >wis 5 2 3 
47. 


When each item is boxed, items of irregular type or shape can be arranged 
in a regular array. Thus, open may be usefully modified by the under 
conjunction "", using open with another verb which is to be applied to each 
item of the boxed argument(s), such as lengths t"» pieces. 


Tolerant Open 


When the arrays contained in the various boxes are of the same type, but 
differ in rank or shape, each result is “padded” as neceasary во that every 


e = gard, the cules for boring i Ап. its om бре кучыш he ыны ты а АЛ. APL2 does not 

Бид to be boxed, but trie Bs sama на акый Since АН maticu boss o sum hove га а 
Erant haz 0, in order jo ave ema and bozas ithe nune му, APL2 requires mita arrays, a 
constituents are boxed but the items ere not. 
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cell in the result has the same rank and shape. In this sense, open is said 
to be tolerant, since it does not require the various arrays to have the same 
shape. Each is given a rank equal to the maximum rank boxed within w 
by logically catenaling leading 1s to its shape vector. Each axis is given a 
length equal to the maximum length that that axis has in any of the boxes 
ino 


кшз” 19«' The quick brown fox.“ 


p»u 


Fill Elements 


Where the array within а box has a length less than the maximum length 
for that axis, the corresponding cell in the result is padded with fill elements 
- extra items to make up the needed length. A character array is padded 
with trailing blanks, a numeric array with 0s, and an array of boxes with 
the enclosed empty box «10. 


Esch cell of the result of >w is expanded to have the common shape of all 
the result cells, as follows: 

cell - the array disclosed by opening а single box in ш 
HaxRank — highest rank inside all boxes in w 

MaxShape - maximum length of the axes inside all boxes in ш 


CommonShape:  MaxShapet*(1[(-MaxRank) tPCe11)PCe11 
This is illustrated in Figure 5-9. 


When you use one of the composition adverbs (described in Chapter 6, 
“Adverbs and Conjunctions”), it is possible to combine open with box for 
each cell. Each box in the argument is opened, processed in some manner, 
and then re-boxed. In that situation, there is then no need for padding, 


5-34 Verbs 


February 1993 


SHARP APL Reference Manual 


Enclosed in cach box 
Е Rank Shape 
2 34 
° 
2 11 
3 413 
1 9 
3 123 
Max 3 439 


Shape of >ш 32439 


Figure 5—9: Shape of result cells produced by tolerant open. 


because the variously-shaped intermediate resulls are not assembled into 
the result until re-boxed.!} 


Monad > 


"When w consists of boxes, the result of monad > is w, unchanged. Bui 
when w is open, >w boxes it. This is why monad э is called conditional 
box. 


You can use the expression «mc to determine whether w is open or boxed. 


Dyad » 


The dyad > (link) forms its arguments into an array of boxes. И always 
boxes a, but it boxes w only when w is open. 


Thus, dyad > can be defined in terms of dyad join , and monad > as 
follows: 


aw € (<0), >w 


М jn APL, the special cass expression a ("> w cormsponds to the APL? sack expresion a f° at 
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The conditional boxing of the right argument lets you use a simple expres- 
sion to box and join several objects without parentheses; 


Who*! Tom'»' Dick'»' Harry" 
рићо 


Who 


|Tom] | Dick] | наггу| 


ho- Janet > 
"АТ I 

Jane] | Tomi | Dick| | Harzyl 

ttl І 

Using link with the rank conjunction lets you link one array with parts 
of another. Consider a compiler that generates declarations for mother 
computer language for a list of names. If names is a list of boxed names, 
then the declarations might be generated as follows: 


тпатез 


foo 
vtom 
Squeeze 
nub 
stat ic VAR % 0 names 
Static VAR 1 
static VAR foo 
static VAR vtom 
static VAR squeeze 
static VAR nub 


Watch ош: When you need to add another box м the end of Who - for 
example, to add '.71121' so that her name follows the other names - it is 
not appropriate to write: 


WhoeWhoa ! J111* 
That would put a new level of boxing around Who, and result in the two- 
item list: 


in This achieves the principal beneft of APL2's vector or amend notation without the syntactic complexities that АР12 
introduces by allowing nouns to be linked simply by jutaposition. 
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To add one more box at the end: 
h- . Jill' 


< > 
Less; Greater 


I^ 


Less than or Equal 


Iv 


Greater than or Equal 


These four dyads are discussed together because they are closely related. 
There is no monad < or 2. Monads < and > are box and open, discussed 
in the preceding section. 

А result cell returned by these propositions contains 1 where the proposition 
is true, and 0 otherwise. The domain is restricted to real numbers. (APL has 
no collating sequence for characters. Hence, comparisons such as ! a* <' bt 
produce domain error.) 

Each of these verbs makes tolerant comparisons, subject to the visible value 
of the system variable Oct. To examine the effect of Oct, let tEqual be 
а user-defined verb whose result is 1 when a and w are equal within the 
limite of tolerance set by Det. a 


СБача1: 0s(Octx{ enr -l 


1 See the discussion of “kermî comparison” іа the section of “equal and unequal”, which follows. 
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Then the following thows how the four propositions « < 2 > are affected 
by Oct by referring to expressions in which the effect of Oct is confined 


to tEqual: 
a e (а<ш) A ха tEqual w 
asw «+» (ач) v а tEqual w 
аш + (а>ы) v а tkEqual w 
ахы + (are) ^ ма tEqual w 


= 7 
Nubsieve; Equal, Unequal 


Identity | Argument 
Dyed | Element | Rank 
[none] | Equal *00 
Nubsieve | Unequal 9 0 0 
Monad > 


Monad # is defined as nabsieve, k produces a Boolean list that marks the 
mub (the unique major cells) of w. For example, with a list argument, the 
unique items are found. With a table, the unique rows of the table are 
found, and so on: 
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#'abacus' 
110111 
b 
mabel 
toto 
lisa 
fred 
lisa 
fred 
dorothy 
toto 
mabel 


1111001000110 
(Ab) Ab 

mabel 

toto 

lisa 

fred 

dorothy 

nancy 

ed 


‘The commonly used expression for the nub of a list 
nubs ((1Pw)swiw)/w 

can be written more efficiently and compactly using nubsieve аз 
пир: (uu) ga 

Formally, nubsieve is defined on lists as: 


ns: ро : xPw з: (<\-а)уа\п5( а+оё1рш)/ш 
For arrays, major cells are used in place of list elements. 


Since nubsieve is defined in terms of tolerant inequality, it is sensitive to 
Осг. 
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Dyad - 
A result cell of aw is 1 when the items compared are equal, and 0 other- 
wise. 
No character is equal to any number; in particular: 


123='123+ 
000 


‘Two characters are equal only when their intemal representations are equal 
(that is, when they have the same position in av, the set of alt possible 
characters). For example: 


a ananas! 
001010 


in a few cases, usually involving characters whose appearance differs ac- 
cording to national convention, a device may generate the same display for 
two different characters. The fact that the displays are indistinguishable 
does not make the characters equal. 


Tolerant Comparison of Real Numbers 


APL judges two numbers to be equal when the absolute difference be- 
tween them is not greater than (ict times the greater of their magnitudes. 
Formally, using the non-tolerant meaning of <: 


(law) t, | ar jw 


APL limits the maximum permissible value of Oct. To be valid, 
Oct mus be a non-negative item less than 16+ 8 (which is about 
2328306437 10-1. 


There аге two practical consequences of the way Oct affects comparisons 
and the limit on the maximum value Oct can be given: 
» Tolerance cannot affect comparisons with zero. That is, no comparison 
in which one of the items is 0 can be judged equal to another unless 
they are exactly equal, This is true regardless of the value of Oct. 


• Tolerant comparison can make a difference only to numbers whose 
intemal representation requires floating point. (Stating it the other 
way, no matter what legal value you give Oct, two numbers whose 
internal type is integer can be reported “equal” only when they are 
exactly equal.) 


ы It yon give Oer e value outside that range, APL dosa not ianmedistely object. It reports Oct: error м the next шм of 
‘thet implicitly refera we Oct. 
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Dyad = 
The verb unequal is the negation of equal: 


суш ж» ~azw 


Match 


The dyad asc retums а Boolean item reporting whether a is identical to 
w. То be judged identical, a and ш must have: 

• the same rant 

* the same shape 

» Throughout that shape, the same value. 


For numeric items, the magnitude of their difference must be no greater 
than Oct times the greater of their magnitudes. (See the discussion of 
"tolerant comparison” in the description of “equal”, earlier in this chapter.) 
Since each item in one array must be equal to the corresponding item in 
the other, arrays that are not empty must necessarily be of the same type 
(numeric or character). However, empty arrays of the same rank and shape 
maich regardless of type. Moreover, the intemal type of a numeric army 
does not affect comparison. For example, an array stored in the integer 
format may match an array stored in floating format, provided, of course, 
that the actual values in the floating point array are equa) (or sufficiently 
close) to those in the integer army. 


Match has infinite defanit argument rank. That is, unless explicitly modified 
by the rank conjunction 9, match treats the entire argument as a single cell 
and retums a single 1 or 0. Modifying æ with the rank conjunction, you 
can define the cells to which it applies. For example: 


L x91 € a Compare list L with cach row of w. 
T a2 w a Compare table T with cach table of w. 


Since empty arrays do not have items which can differ from one another, 
they match if their ranks and shapes match: 


trao 
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^ 
Not 
Identity | Argument 
Element | Rank 
The monad ~ (ло!) is defined only on Boolean arguments; that is, arguments 
whose values contain only 1 or 0. For 1 it retums 0; for 0 it retums 1. 
The dyadic case of ~ is undefined. 
AVAN 


LCM, GCD; And, Or; Nand, Nor 


Numeric Boolean 
Arguments | Arguments 


Identity | Argument 
Element | Rank 


^ |LCM And 1 *00 
v |GCD Or *00 
^ | [undefined] | Nand *00 
м | [undefined] | Nor * 00 


Boolean Arguments 
For Boolean arguments (0 and 1), the v is equivalent to the logical or, and 
the A to logical and. Thus: 


ped 1 
vb 4 


11 


The verbs ^ and У (called nand and nor) are defined only on Boolean 
arguments. They are negations of ^ and v; that is: 


ам) چم‎ “ало 


aw ж» ~avw 
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peo 1 
pep 

10 

0 0 
penap 

11 

10 


Non-Boolean Arguments 


For non-Boolean numeric arguments, the expression алел retums the least 
common multiple (LCM) of a and ш, while av« returns the greatest com- 
mon divisor (GCD). For example: 


12v30 
6 
12430 
60 
12 0 
25 
v/12 30€12v30 
1 
3.6۷4 
0.4 
3.6 
36 
X + 6250 8750 11250 16250 
* + V/x 
57913 
у * 0.03135 0.04389 0.05643 0.08151 
y + М/у 
5 7 9 13 


Fraction + 17464 
(Fraction,1) + v/Fraction,1 
17 64 


Except when one of the arguments is 0, the GCD and LCM are related by 
а duality akin to DeMorgan's law for Boolean А and v: 


aww o> aa AU س‎ 
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When one argument is 0, the result of LCM is 0 and the result of GCD is 
the other argument. 


Tolerant GCD and LCM 


For arguments other than Booleans, Aw and амо are subject to the vis- 
ible value of Oct, comparison tolerance. Tolerant computation permits 
reasonable results with fractions that cannot be precisely represented. For 
example, the least common multiple of 0.6 and 1.4 is 4.2. This result 
is retumed correctly with the default value of Oct. But if Oct is set to 
0, APL fails to detect that each is an integer multiple of 0.2, and hence 
retums an LCM as if they had no common factor: 


Oct 
1.4196976936714 

EALA 
4.2 

Qt -o 

EALA 
3.02641895е16 


Fd 
Right, Left; Dex, Lev 


Identity | Argument 
Moned | Dyad Element | Rank 


+ | Right | Right Dex | [none] | оо о оо 
+ [Let — | Left; Lev 


[none] | оо оо оо 


Dyads + and 4 


The dyads + and 4 retum one argument and ignore the other. The argument 
retumed is the one to which the horizontal part of the symbol points: 


aw e w 
aw =» a 


The same principle applies to the monads. However, in that case there is 
no left argument. The definition becomes: 


wi w 


аә e [No result} 
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Dex is used primarily to pass an argument cell into a composition without 
changing it. For example, the cut conjunction modifies a monadic verb to 
apply to cach segment of an array argument. If you wish merely to select. 
the segments without transforming them, + does it, 


Left, ос lev, is used primarily to assign а value that cannot otherwise be 
syntactically fitted into an expression. For example, mathematicians are 
fond of sentences in the form “x is such-and-such a function of y, where у 
ів..." That is really two sentences, linked by “where.” In "A Dictionary of 
APL,” Iverson illustrates a similar construction thus: The following expres- 
sion determines the coefficients с of a polynomial equivalent to a polynomial 
with roots r: 


-S. pr. at 43+(11+п)»,2+46 Atebrix/b 4benP2 Aneer 


In this style, you start with the conclusion c«s*. xp and then fil in the 
subordinate definitions. If this were broken into а succession of short sen- 
tences, they would appear like this: 


ner 

Nn 

tebTix/b 

S- Gin). 27 
perx.kt 
сез+.хр 


In the foregoing, each of the segments linked by ~ assigns а value to а noun 
used in the root phrase. If there were no assignment, whatever is to the 
right of ч would be completely discarded during evaluation. This might be 
the desired outcome when the material to the right is а comment, intended 
for the human reader but to play no part in the interpreter’s execution. For 
example, in the following, the text that appears as the left argument of + is 
discarded, while the value to the right is passed through: 
aewx count to n'Fin *'length of r'epr. 


The verbs ~ and + are regular in their syntax and provide an altemalive to 
the irregular separators © and ^. 
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Tl 
Encode; Decode 
Identity | Argument 
Monad Русі Element | Rank 
T | [Undefined] | Encode; Represent | [none] | * oo оо 
1 | [Undefined] | Decode; Base [none] | * oo оо 
Dyad T 


The dyad т constructs the representation of each number in w in the number 
system whose base (also called radix) is a. The dyad 4 is the inverse of 
encode, the base value of the representation û in that number system. 


For example, to represent а time interval recorded as 3723 seconds as а 
triplet in base а+24 60 60 (hours, minutes, seconds): 

24 60 6073723 
123 


And conversely: 


24 60 6011 2 3 
3723 


Relation Between Representation and Residue 


А representation is calculated as a series of residues. This is made explicit 
in the following definition, which calculates a representation of in base 
а, when w is an item and a is a list: 


V 2-а rep ш; pv; 1 
C1] — i«üiopz-a,a 
(2)  pveweights п 
[3] 10:+(040>1+1-1)#0 
[41 20 £]-aC4] l, prt i) 
[5] CAD pt) 
[6] +20 

y 


In the definition, pv is the position value for the base. For example, in 
the familiar decimal system of representation, the right-most position is the 
units position, the next tens, the next hundreds, and so on. A length-4 
representation in base 10 has position values 1000 100 10 1. The value 
of pv is calculated by the verb weights, defined thus: 
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weights: 14фх\фа,1 
No matter what the value of а, the value of the right-most position retumed 
by weights is always 1. 
Note that T is not tolerant (that is, is not sensitive to Oct), 
‘There is a limit to the range of values that can be represented in a base of a 
given length. The largest integer representable in base а is a1a-1. More 
generally:'* 

азатш e (x/a)|w 
rather than w; for example: 


(3010)13247 
247 

10030100 73247 
247 


The result 247 is (x/3P10) | 3247. 


However, as a consequence of the definition of O-residue, when the base 
begins with 0, there is no limit to the value of the first clement of the 
representation and any necessary extra can be accumulated there: 


0 10 1073247 
3247 
Since the last position in any representation is the units position, the frac- 
tional part of w always appears in the last position of the result:i* 
(3010)1247.33 
2 4 7.33 
Combining the previous two remarks, the 0 1 representation of a number 
separates its integer and fractional parts: 
0 17247.33 
247 0.33 


When a negative number is represented with a positive base, because (һе 
representation is derived from the x/a residue, the value retumed is the 
complement in that base. For example: 


(40100 1 
9 9 9 9 Tens complement of 1 


Wa het -O so that Û is not bla 
* Fractional values may also occur in other parts of the mpresentation when the base itself contains fractions. 
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(40160771 
15 15 15 15 Familiar (to those who use Баѕе-16) as FFF 


0 177247.33 
7248 0.67 


Higher-Rank Arguments to T 
Fundamentally, encode takes a number from w and represents it according 
to а base specified іп a. The number being encoded is an йет. The base 
is specified by a list. 
When w contains many numbers, the result contains a representation for 
each of them. In the result, the representations are spread along the first 
axis;!" for example: 


(4010) т 1987 2001 44 


oon 
eoon 
e owe 


When @ contains many bases, the result contains a representation for each 
number in each base. 


Within a, the list that defines cach base is spread along the first axis of u. 
For example, suppose you want numbers to be represented with base 10 
10 10 10 and also with base 0 1000 1000 1000. The two bases must 
form a 4-by-2 array thus: 

10 0 

10 1000 

10 1000 

10 1000 


Similarly, when a has shape 3 4 5, dyad т treats it as а 4-by-5 table of 
three-element bases. 


In the result produced by T, each representation is spread along the first. 
axis. When there are several representations for cach number in w, you get 
first the axes corresponding to the various representations, then the axes of 
w, Thus: 


o e» (Pa), pw 


M This ua of tho бги апи Ber. with би genera rel that an argument cll occupies ihe ан алы. 
sate гриб ive 1 эм! en p 
achieved by conjoining repressor wich rank: GT*1 0 ez ме “Forcing Representation Cells w the Lart AX", below, 
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For example, suppose a contains the two bases: 


a-(4P10), 70 1000 1000 1000 


Then, the two representations of a single items arc retumed as a 4-by-2 


table: 


1 
9 
8 
7 


aT1987 


0 
0 
1 
987 


And the two representations of three items are returned as a 4-by-2-by-3 
array, thus: 


1 


ү; 
987 


a T 1987 2001 744 


2 
0 


0 
0 


0 
2 


1 
1 


956 


Forcing Representation Cells to the Last Axis 


You can obtain a more consistent placement of the new axis (that is, putting 
it at the end) by using the rank conjunction * to specify explicitly the cells 
of each argument. When you do that, the standard rules for frame-building 
apply. For example, the following expression generates all the distinct 
representations possible in three binary digits and makes each representation 


February 1993 


a row of the resulting table: 


9 9 0 
"eoorroo 


2 2 


2 2 2191 0 62230 
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By electing to modify Y with the rank conjunction, you give up its special 
rules for higher-rank arrays and instead apply the general rules for agree- 
ment of frames: either the frames must match, or, when one frame is empty, 
its single cell is paired with every cell in the other frame. 


Dyad 1 


Dyad 1 is inverse to dyad т. While 7 generates the representation of a 
number in a particular base, 1. returns the numeric value of a representation 
w, interpreted in base а. 


As with T, the base is described by a list. However, the base may also be 
an item, in which case APL treats it as a list having the same length as the 
first axis of w, 


As with T, for each base there is a corresponding set of position values, they 
can be calculated by the same verb weights described in the preceding 
section, "Relation Between Representation and Residue". The base is 10 
10 10 10,the position values are 1000 100 10 1. 


The base-value of a representation is the sum of the numbers in the repre- 
sentation, weighted by their position values: 


аш e +/exweights a 


For example: 
«+24 60 60 
wel 2 3 
аш 

3723 
weights а 

3600 60 1 


+/uxwelghts a 
3723 


{tem Left Argument 


When а is an item, it is treated as (71+Рш)ра. Thus: 


2110 1 
5 


This permissive treatment of the left argument is possible for 1 but not for 
T. 
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Higher-Rank Right Argument 


Pundamentally, base takes а number-representation from w and evaluates it 
according to а base specified in з, The representation being evaluated is a 
list, and the base is a list of the same length. 

When w contains many representations, the representations are assumed to 
be spread along the first axis. For example, suppose b is the following 
4-by-3 table: 


* 


2 
0 
0 
1 


3 


The base - 10 values of its three representations are: 


(4010) 1 b 
1987 2001 9956 
When you provide a right argument of higher rank, the representations are 
ЭШ assumed to be spread along the first axis. For example, if w is 4-by-5- 
by-6 array, APL treats it as a S-by-6 array of-four-item representations. 


Higher-Rank Left Argument 


The base is assumed to be spread along the last axis of a. For example, if 
you provide а 2-by-3-by-4 left argument, APL treats that as a 2-by-3 array 
containing six bases, each of four elements. 


The result contains a dase-value in each base, for each representation. 


The shapc-agrcement rules for 1 are the same as those for inner product. 
The last axis of а must maich the бги axis of ш. This axis disappears from 
the result (since the value is the weighted sum along it). 


The remaining axes are reproduced in the result, The shape of the result is: 
р aw ep» (it), (1400) 


Length-1 Base 


As noted, when the left argument of 1 is an item, it is treated as а list whose 
length matches the length of the representations in w. More generally, 
whenever the last axis of a has length 1, it is assumed to apply to the 
representation in w, and so is extended to match the length of the first axis 
of a. 
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Forcing Representation Cells to the Last Axis 


Just as you can use the rank conjunction to force the representation to Ше 
along the last axis of the result of T, so you can force 1 to accept arguments 
in which the base is specified by the last axis of a, and representation cells 
are found along the last axis of w. 


Suppose b is а table containing two bases, 24 60 60 and 37100, thus: 


b 
24 60 60 
100 100 100 


Then you can evaluate the representation 1 2 3 in each base by: 
D 171 +i 23 

3723 10203 

От suppose с is the following four-column table: 


"oo 
ooon 


9 
1 
0 


оон 


< 


fou can treal с as three representations, each of length 4, and evaluate each 
of them in base 0 24 60 60, thus: 


0 24 60 60 1*1 c 
86400 3600 60 


(This gives you the number of seconds in a day, an hour, and a minute.) 
By electing to modify 1 with the rank conjunction, you give up its special 
rules for higher-rank arrays and instead apply the general rules for agree- 
ment of frames: either the frames must match, or the single cell in an empty 
frame is paired with every cell in the other frame. 


Limitations on Inverse 


In principle, T and 2 are inverse to each other. But this is restricted in two 
ways: 

* Base. The representation returned by атш) is in fact the representa- 
tion of (x/a) lu. When w is outside the range 0 through ^14x/a, 
information is lost, and dr is not equal to w. 

o Higher-rank arguments. When a is a table of bases, T and 4 have 


different assumptions about how they are arranged and how they affect 
the result. The inverse relationship between T and 1 holds only when 
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a is a list, or when both T and 1 are modified by the rank conjunction, 
as T91 0 and 191. 


Evaluation of Polynomials 


If c is a table containing the coefficients of the successive terms of a 
polynomial, then хс evaluates the polynomial. The table of coefficients 
must contain a position for each term of the polynomial, in descending 
order, that is, starting with the coefficient for the x* term and down, in 
order, to the constant (that is, the coefficient of x*). This is the common 
order for the representation of numbers; however, polynomials are often 
‘written in the reverse order, with the low-order term first. 


LÀ 
Format 


The format primitive * accepts any array as argument and produces a char- 

acter representation of that array as a Kult!“ 

The result of v has the same rank as the argument, except in cases of 

formatting boxed arrays or non-character scalars. However, while axes 

other than the last have the same length as the argument, the last axis 

is often longer. Each numeric item in the argument is represented in the 

result by a format that usually requires several characters, perhaps including 

blanks as delimiters. 

‘The representation of numbers is affected by the following system nouns: 
Орр Print precision. The number of significant digits used by monad 


Ops E and spacing. Alignment within and between cells for 
display of an array of boxes by monad v. 


Ofc Format control. Format conventions for dyad v. 


Default Display 


APL automatically displays the final result of any sentence that has a final 
result but does not assign that result to a name. Similarly, any noun assigned 


а Тыва ea Пепо provides f. varity of bs than those available with ¥, controlled in a somewhat differat 
ten k is described im Chapter 11, “System Nouns and Verbs”. . 


February 1993 Verbs 5-53 


SHARP APL Reference Manual 


to O or D is displayed. In these cases, where format need not (and cannot) 
be explicitly specified, the format is the same аз that produced by monad 
M 


Monad ¥ 


Monadic format converts an array whose items are numbers or boxes іо а 
character representation. Packages are outside йз domain. Applied to an 
array of characters, tw returns w unchanged; that is, wzw, 


Applied to an array of boxes, ¥ opens and formats the contents of cach 
box independently, and then arranges the separate item-formats into à grid 
representing the structure of the array (as is explained later in this section). 


Applied to a numeric array, ¥w retums a character array in which the 
numeric values are represented in one of three possible formats: 


. Fixed-point. This form shows a leading zero only in the units position 
and does not print trailing zeros to the right of the decimal point. The 
decimal point appears only when there is a digit to the right of it 
(so integer format is simply a special case of fixed-point format). A 
negative number has a macron (high minus sign) before the first digit. 
For example: 

* 8 12 + 78 В ^8 
70.875 1 71.5 


Exponential. This form, also called scientific notation or engineering 
format, consists of two parts, mantissa and exponent, joined by the 
letter е. In scientific notation, the mantissa is a number less than 10 
and at least 1 (except when the number being represented is 0), written 
in fixed-point format. The exponent is an integer indicating the power 
of ten by which the mantissa must be multiplied. For example: 

¥125 x 10w12 
1.25e14 

*7 ж 12 13 
1.38412872e10 79.688901041e10 


Engineering format is similar to scientific notation, except that the 
exponent is always a multiple of three. 

Complex. This form consists of the real and imaginary parts linked 
by the letter J. The parts may be represented in any of the formats 
(integer, fixed-point, or exponential), independently of each other. For 
example: 

327 + 0/1612 
27/1612 
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When the imaginary part is 0, monad ¥ includes neither the character 
0 nor the letter J (and the format of the real part is the same as 
fixed-point or exponential format), For example: 

3750,36j47.52 + 374 495 х 0.127716 
14 30.12/715.88 


Array-wide Format vs. Item-by-item Format 


Under some circumstances, a single format is adopted for an array as a 
whole, and all items are formatied and aligned in the same way. Under 
other circumstances, each йет in an array is formatted independently. 
An am- wide common format is adopted when: 
the array’s rank is greater than 1 
and 
+ no item in the array uses 7 format (that is, has a non-zero complex 
part). 
Conversely, independent item-by-item formatting is adopted when: 
the array has rank 1 or less 
or 
a any item in the array uses J format (that is, has a non-zero complex 
part). 
When a common formal is adopted for an entire array, either all items are 
shown in fixed-point format, of all items are shown in exponential format. 
in either event, all columns have a common field width? Within each 
field, the units position of cach representation is at the same place, so that 
it is vertically aligned with the others. In exponential format, the units 
positions of the mantissa are aligned, 


Choice of Fixed-Point or Exponential Format for Real Numbers 
When wis real? APL selects a format as follows: 
» A number? whose magnitude lies in the range 10& 6 to 10%0рр is 
represented in fixed-point format. 
A number that is exactly equal to zero is represented as 0. 
. A number outside those ranges is represented in exponential format. 


? See the discussion of "Field Width in Tables", later in this section. 


er к» itid рола, bey өн Чары! oa. Bat since the poini is omitted when there ме ро digits after it, it is 
sar to say tha tbe units positions are aligned. 


“Real” is used here in the mathematical sense of “having по imaginary part”; й does not exclude integers. 
Or part (real oc imaginary) of а complex number. 
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Notice two useful consequences of these rules: 


. їп fixed-point format, no value of Орр can discard digits to the 
Jefl of the decimal point 


* Anumber for which APL's rules require exponential format could 
not be written more briefly in fixed-point format. 


in an array having two or more axes and in which no element requires a 7 
їп its representation, APL uses exponential format for the entire array when 
any of the following is true: 
. The largest magnitude in the array is greater than 10%0рр. 
. The smallest magnitude in the array is less that 104-Прр+4. 
. The range from the smallest to the largest magnitude exceeds a factor 
of 10*QppH4. 


Mixed Formats in Representation of a List 


Ina list, APL selects fixed-point or exponential format for each of the items 
independently. For example: 
Opp+s 


v0.2x10*6x7 3416 
2е713 0.0000002 0.2 2e5 2e11 2e17 


Appearance of Fixed-Point Format 
А number formatted by monad ® in fixed-point format is displayed with: 
. no more than Орр significant digits. 
+ no trailing zeros to the right of the decimal point. 
+ A leading zero to the left of the decimal point only in the units position. 
. A decimal point only when there is a digit to the right of it. 
. A macron (high minus) ~ before the first digit of a negative number. 
For example: 
üpp-4 
v; - 10000 100 143 
73333 


733.33 
70.3333 
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Appearance of Exponential Format 


in exponential format, each value being formatted is represented by a pair 
of numbers, the mantissa and the exponent, with an е between them. 


‘The exact form of the mantissa depends on whether each item is formatted 

ly or there is an array-wide uniform format, When items are 
formatted independently, trailing zeros to the right of the decimal point are 
omitted, and the point is included only when there are digits (о the right of 
it For example: 


"10 11 12 * 10 ¬ Ûpp*4 
1е10 2.594е10 6.192e10 


However, with an array-wide uniform format, every item has the same 
mantissa format and the same exponent format. If any mantissa requires а 
decimal point, they all have one. If any requires positions to the right of 
the decimal point, they all do. ‘The greatest number of trailing decimals is 
Орр-1. 


The exponent is expressed as an integer. It may have one or two digits and 

perhaps a negative sign (when the magnitude being represented is Jess than 

1). Space is allocated to accommodate the exponents needed for the actual 

dala; at most, the exponent takes three print positions (o accommodate а 
negative two-digit exponent), For example: 


¥3 2P1042/5 6 7 


1e5 1e5 There is only one digit before е 
1e6 1e6 because all mantissas can be represenled 
le? 1е7 by a single digit. 

93 20105 5 6 6 7 70 
1e5 1e5 Both columns have space for a two-digit 
126 1e6 exponent even though only one column 
1e? 1870 requires two digits, 

W1 1 x91 +3 20105 5 6 6 7 70 
“leS 1е5 Both columns have two positions before e 
“1e6 les even though only one column uses both 
71e? 1е70 of them. 


*(10*5 6 7), 3 1P10 11 12 * 10 ч Opped 
1.000e5 1.000810 The mantissas on the left have trailing 
1.000e6 2.594e10 zeros to make them match the width 
1.000e7 6.192е10 of mantissas on the right. 
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The exponent is always positioned flush-left next to the e. Thus, even when 
the letter е is aligned, the units position of the exponents їз not necessarily 
aligned. For example: 


Црр+4 
¥70 2, (43)x10410 11 
0.00060 
2.00060 
3.33389 
3.333e10 
3.33313 


12 


Appearance of Complex Format 


When any item in an array has a non-zero imaginary part, thal item is 
displayed in complex format, with a j between the real and imaginary 
parts. (Conversely, in a complex array, an item whose complex part is zero 
is displayed in the usual fixed-point or integer form.) 


The real and imaginary parts of each number are formatted independently; 
each may be in fixed-point format or in exponential format, without regard 
to the format of the other. There is no array-wide uniform format for an 
array in which any item is represented in complex format. 


In а list, the representations of complex numbers may vary in length. Suc- 
cessive items are separated by one blank, thus: 


( 2 4 6 8) 3 -d 
0.6371.091 0.7937/1.375 0.9086j1.574 171.732 


For an array of rank 2 or higher, each number's representation appears 
flush-right. Within the field devoted to a column of w, there is no attempt 
10 align the letter J or either of the units positions. 


эз(- 6 8 0 66 68)*+3 -Орр=4 
0.908671.574 
151.732 
° 
2.02153.5 
2.04173.535 


Field Width in Tables 


Field width is the number of character-positions allocaled to receive the 
representation of a number. When APL formats a table, it calculates a 
single value of field width for the entire table. The field width and the 
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location of the units position within it are calculated as though all the 
numbers were in a single column. 

The field width adopted throughout an array is the minimum width in which 
all the values can be represented. The field includes an extra column for the 
negative sign only when needed іо represent a value whose representation 
extends all the way to the left side of the field 

The maximum field width of an array in either fixed-point or exponential 
format is 6+Qpp.* Thus the rule for selecting one format or the other can 
be restated thus: fixed-point format is used unless it would require a width 
greater than 6-+0рр. 

The field width of a complex array of rank 2 or greater is the length of the 
longest representation. The greatest possible width is thus 1 (for the letter 
J) plus 2х6+0рр. 


Blanks Between Columns 
In every array having two or more axes and two or more columns, one 
column of blanks is inserted between adjacent fields. 


Examples of Monad ¥ 


‘The following examples are intended to illustrate the points just mentioned. 
In particular, you can see that the same format is used throughout the display 
of a real numeric table: 


¥2 40411212 
1 0.51 0.5 
a 0.5 1 0.5 


72 4p3312 3 


0.3333333333 1 0.5 0.3333333333 

0.3333333333 1 0.5 0.3333333333 
#71 1 «.x 2 4p43 1 2 p- 

70.33333 71 70.5 0.33333 

0.33333 71 70.5 70.33333 

0.33333 1 0.5 0.33333 

0.33333 1 9.5 0.33333 


For the expooential format, that ia Орр digits, plus the decimal point, the Ener е. possibly а sign for tha value and. 
far exponens, n possibly two digits for бю покра of ia exponent oe 
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Separation Between Planes of Higher-Rank Arrays 


As noted at the beginning of this section, in general the result of * has the 
same rank as йз argument. In displaying any array of rank greater than 
2, APL inserts an extra blank line to separate successive rank-2 segments 
(tables), two extra blank lines to separate successive rank-3 segments, and 
зо оп. You can see such a blank line in the preceding example. 


Neither the newline character at the end of each row, nor the newline 
characters required to produce these additional separations, are part of the 
result of ¥, but appear as a consequence of the number of axes in the 
result! 


Format of an Array of Boxes 


When w is an array of boxes, ¥ is always a table. Each of the boxes is 
opened and formatted independently, without regard to the formatting of 
any of the other boxes. The display of each box looks the way it would 
if the object within were to be displayed alone. The display for each box 
is a table, regardless of the rank of the object being displayed. When the 
array enclosed in the box has rank greater than 2, the separations between 
sub-arrays appears as extra rows of blanks. 


The process of opening boxes and displaying their contents is recursive, 
That is, a box may itself contain boxes, and when it does, each is formatted 
according to the same rules. 


"When a table has been computed for each box independently, they are as- 
sembled into a grid corresponding to the structure of the array. However, 
the tables that represent the various boxes may vary in size. Each column 
(that is, each position along the last axis) is allocated а common width 
sufficient to accommodate the widest table in that column, Similarly, each 
row (that is, each position along the next-to-last axis) is allocated а com- 
mon height sufficient to accommodate the tallest table in that row. ‘This 
preserves the alignment of the boxes, albeit by creating a grid whose rows 
and columns vary in width. The effect – rather like а plaid blanket — is 
illustrated in Figure 5-10. 


24 However, when monad ¥ is applied of boxes, the representation never has rank greater than 2 aod 
E d та set ee ined Reber үсүн 
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Figure 5-10 : Preservation of grid structure in formatting an array of boxes. 


In Figure 5-10, where the grid provides a box more space than it needs, 
each box appears at the top left comer of its space. 


Effect of Ops on Position and Spacing of Boxes 


Each box is allocaled height and width sufficient to accommodate the tallest 
box in its row or the widest box in its column. Unless the boxes have dis- 
plays of the same shape and size, some will have more space allocated than 
they need. How boxes are positioned within the space available to them 
is controlled by the first two elements of the system noun Ops. Vertically, 
boxes may be at the top, center, or bottom of the available space; horizon- 
tally, they may be at the left, center, or right. This control applies to the 
array as а whole; there is no direct provision to position some boxes one 
way and some another. The default value of Ops is 1 1 0 1. 


To separate adjacent boxes, you can set Dps[3 4) so that additional blanks 
arc inserted between the rows and columns. Provided Ops{31 and Ops[ 41 
have a magnitude no less than 2, you may also elect to have horizontal or 
vertical demarcation lines around each box. 
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Position: The First Two Elements of Ops 


At the top of the rectangle 
Vertically centered in the rectangle 
At the bottom of the rectangle 
At the left of the rectangle 
Horizontally centered in the rectangle 
At the right of the rectangle 


Spacing: The Last Two Elements of Ops 


Magnitude | Number of positions separating 
vertically adjacent items 
ps3) 
When | Draw lines at top and bottom 
negative | edges of boxes if space permits 
Magnitude | Number of positions separating 
horizontally adjacent items 
Ops{4) 
When | Draw lines at left and right 


negative | edges of boxes if space permits 


When Ops{3) or Lips T4) is negative, the character is used to mark 
the top of a box, the character _ (o mark the bottom, and the character | 
to mark the sides. Where a box touches the edge of the space assigned 
to it, the border characters surrounding the box overwrite the first of the 
separating blanks on that edge. For that reason, border characters may be 
drawn around a box only when there is space for them: that is, when the 
magnitude of the controlling item in Ops is at least 2. 


At the edge of the result of ¥ there are no separating blanks. There, the 
border characters are placed in an additional row or column. Thus, when 
Gps(3) is 72 or less, the result has two extra rows, one at the top and one 
at the bottom. Similarly, when Ups L 4) is 72 or less, the result has two 
‘extra columns, onc at the left and one at the right edge. 


me following example illustrates the effects of Пр» on an array of boxes: 
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Be2 2P(3 SP'AB')21 22'CD'' EFGHIJ' 
YB üps«71 1 73 73 a Top lefi, draw boxes 


ГАВАВА| |1 21 
|ВАВАВ| |__| 
|ABABA| 

— 

mt jM 
col | EFGHIJ| 


эв ps- 1 1 0 0 a Top left, no spacing 
ABABAl 2 
BABAB 
ABABA 
CD EFGHIT 


эв p- 00 0 ^ Centered, no spacing 
ABABA 
BABAB 1 2 
ABABA 
CD EFGHIT 


Dyad + 


The result of атш is a character array in the same way as the result of 
monad ¥. The left argument permits more specific control of formal and 
field width. It describes a series of fields, each to contain the representation 
of a column of to. The fields are described in three different ways, depending 
upon whether а is empty, numeric, or character. 


Empty a The right argument is formatted according to the rules for 
monadic format, as if the expression were wo instead of азо. 


Numeric a Each field is described by a pair of integers. In general, а 
is a list with twice as many items аз ш has columns. The 
first member of each pair sets the width of the corresponding 
field. The second member of each pair sets the number of 
fractional positions or the number of significant digits. 

Character a “Format by example." a is a character list having the same 
length as the last axis of the result. Embedded within œ are 
characters indicating by example the position and format of 
the various fields. 
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Dyad v with Empty o 


When a із an empty vector, ажи formats w according to the rules for 
monadic format, as if the expression were vo. This is useful when creating 
reports containing mixed character and numeric data: 


пате+4 5P'MariaPhil ElenaKen ' 

paye4 1P 34000 125000 193000 17000 

14+123 456 789 666 

tei 3P'Employee name rd '»'Salary ' 

vt;(*!25 026 0)V"»name»id»pay + Ops+0 
Employee Name Userid Salary 


Maria 123 34000 
Phil 456 125000 
Elena 789 193000 
Ken 666 17000 


Dyad ¥ with Numeric a 


When w is numeric, aww formats each of its columns according lo the 
specifications encoded in a, As with monad ¥, "column" here means а 
position along the last axis. 


The left argument a requires two integers to specify the format of a column 
of ш. Each pair of integers in œ controls the formatting of a column of w. 
Alternatively, a may be a single pair, which applies to alf the columns of 
w, or a single integer, in which case it is treated as if it were the pair 721a. 
Otherwise, length error occurs. 

"Within each а-раіг, the first integer controls the width of the resulting 
representation. The second integer controls the type of representation (fixed- 
point or exponential), and the number of places to the right of the decimal 
point (in a fixed-point representation) or the number of significant digits (in 
an exponential representation). 

Both types of representation, fixed-point and exponential, are right-justified 
within their fields. In fixed-point representation, the number of places be- 
yond the decimal point is fixed and filled with trailing zeros. 

То provide blanks for visual separation of fields, assign a width greater than 
needed to represent the values in w, so that the field has leading blanks, 


Fixed-Point Representation 


The first member of an a-pair specifies the total width of the field. However, 
when the first member of the field is 0, the ficld is made wide enough to 
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accommodate the widest representation in that column, plus one leading 
blank. 


The second member of an a-pair specifies the number of places to the 
right of the decimal point, When the number of places is greater than 0, an 
additional position is required for the decimal point itself. Unused positions 
lo the right of the decimal point are filled with trailing zeros. 

To represent a negative value in w, the negative sign is inserted to the 
left of the left-most digit. When calculating the width required for a field, 
you should allow space for the negative values actually present in the data. 
When the field lacks space to print the sign for a negative value of w, there 
is a field overflow. What APL does then depends on the value of Ur et 4]. 
(See the discussion of Ofc later in this section or in Chapter 11, “System 
Nouns and Verbs) 


To illustrate formatting rules, consider the table m created as follows: 


me((43) x 10415) «.х 1 1 1 p 


эт 
3.3333 3.3333 73.3333 
33.333 33.333 733.333 
333.33 333.33 233.33 
3333.3 3333.3 3333.3 
33333 33333 733333 


‘To show the boundaries of the result, catenate brackets to the lefi and right: 


c e 282), 11! 
(03.3. 3.33 73.331 
{ 33.33. 33.33 733.33] 
С 333.33 333.33 7333.33] 
[ 3333.33 3333.33 3333.33] 
[33333,3333333, 334: 000006] 


At the lower left, representations run together because a field width of 
В is insufficient to leave an initial blank. At the lower right, there is 
field overflow because field width @ is insufficient to represent the number 
733333.33. 


Field width 0 causes ¥ to calculate the width of the fields. A single pair 
beginning with 0 computes the minimum common field width for the сайте 
array: 


5 Recall that Opp affects monad Y but not dyad ¥. 
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C, 251, 1,1 


t 1.00 3.33 3,33 73.331 
t 1.00 33.33 33.33 733.33) 
[4 1.00 333.33 333.33 7333.331 
t 1.00 3333.33 3333.33 73333.33] 
t 1.00 33333.33 33333.33 733333.331 


Specifying 0 2 for each field separately permits cach column to be assigned 
its own width, independently of the others. It allows space for a negative. 
sign whether or not there is one in the corresponding column of ш, 


c, (0 20 2 02 02 1. 1 °) 
1.00 3.33 3.33 73.332 
1.00 33.33 33.33 23.33) 
1.00 333.33 333.33 333.33) 
1.00 3333.33 3333.33 3333.33 
1.00 33333.33 33333.33 733333.331 


Exponential Representation 


When the second member of an а-рай is negative, the result is represented 
in exponential form. The first item of an a-pair sets the total width of the 
field, while the absolute value of the second member specifies the number 
of significant digits. In an exponential representation, positions are required 
as follows: 

. The last three positions of cach field are reserved for the exponent and 
its sign. They are set flush-left within those three positions; unused 
positions are filled with blanks. 

+ The fourth position from the end is reserved for the character e. 

. In the remaining leftward positions, there must be space for the fol- 
lowing: 

* The number of digits specified in the first member of the pair. 
‘The first of these digits appears to the left of the decimal point; 
the others appear between the decimal point and the character e. 
* A negative sign, if required for the value being represented. 
In general, the total width must be at least 6 grealer than the number of 
Significant digits requested. However, when the value being represented is 
not negative, a width 5 greater than the number of significant digits suffices. 
Any unused positions at the left of the field are filled with blanks. The 
following illustrates some of the points mentioned: 
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te2/ (1063) x 1 1 1e730 
»“, (8 73. 15 73 ж р), ЭЛ 


(3.33e0 3.33e0 ] 
[ikea 73.33e0 7 
(3.33e730 3.332 301 


Dyad * with Character a 


When a is a character array, the expression atw is called format by example: 
а provides a pattern for the result. The right argument c is a numeric array 
of any rank. The left argument a is a list of the same length as the last axis 
of the desired result and shows how each column of із to be represented. 


The system noun Ofc is an implicit argument to dyad ¥ and controls how 
jt treats certain cases, as explained below. 


Numeric Fields within the Pattern 


The left argument a consists of a series of numeric “fields,” optionally 
embedded in non-numeric text. The representations of the numbers in w 
replace the numeric fields of the pattem. а must contain either а numeric 
field for each column of w or a single numeric field that is then applied to 
all columns of w. 


A numeric field must contain at least one digit. It may also contain the 
characters . (dot) and , (comma). Collectively, the digits 0 through 9 and 
the dot and comma are called control characters. (Whether a dot or comma 
serves аз а control character depends on context, as explained below.) 


A field is bounded by blanks or (on the right) by the first non-control 
character occurring further right than a 6. For example, the following has 
three numeric fields, pointed out by the arrows shown below. The first 
numeric field is ended by the colon, since colon is the first non-control 
character to the right of the 6. 


‘part $ 05555-60: Stock 55550 Updated 55/55/55" 
О 1 ettet 


Although the presence of one or more blanks serves to delimit a field, cach 
blank is reproduced in the result. 


The digits in a field reserve places in the result to receive the representation. 
of a number. If they fail to provide sufficient positions, there is a field 
overflow. In the result, the numeric Geld for that value is shown only by 
asterisks (or by the character you indicate in rot 41). 
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By their values, the digits in the pattern's numeric fields indicate how the 
number is to be formatted. Much of what follows concems the effect of 
the digits 0 through 9 on the representation of a number. 


‘The examples that follow make use of а user-defined verb on. It shows 
the left argument of ¥ and then the result, aligned one above the other so 
that you can compare the result with the "picture" that controlled it. The 
argument of ¥ is shown with а row of dashes before and after it, thus: 


а+'550 # $340.10CR ea. = $3,540.10CR* 
de3 2р10 188.4 2 4 20 .12 
a on a ¥ d,x/d 


550 @ $340.10CR ea. 


10 € $186.40 еа. = $1,884.00 
28  $4.00CR ea. $8.00CR 
20 в $0.12 еа. = $2.40 


Decorators within the Pattern 


Characters that are not control characters are called decorators. in the 
preceding example, the characters o, $, CR, ea., and = are decorators. So 
were the texts Part # and Updated in the earlier example, and the hyphen 
and slashes, even though they were embedded within a numeric field. In 
general, decorators are simply reproduced unchanged in the result Those 
that are always reproduced and never float are called simple decorators. 


A controlied decorator is text attached (о the beginning or end of a numeric 
field, usually to indicate the sign of the number there represented. In the 
example, $ and CR are controlled decorators because each of them abuts a 
numeric field. 


A controlled decorator floats: that is, К moves inward to occupy positions 
that the ранет reserved for the number's representation, but that were un- 
needed for the value being represented. In the pattern, a controlled decorator 
is a sequence of one or more characters thal: 

+ does not contain a blank 


. is located immediately to the left of the numeric field's first digit, 
or immediately to the right of its last digit. 


The way the controlled decorator text appears in the result is controlled by 
the presence of the digits 1, 2, or 3 in the numeric рап of the pattem. 
(If the pattem does not contain one of those three digits, or there is a 4 
somewhere between the decorator text and the number 1, 2, or 3, text that 
would otherwise be а controlled decorator is treated as a simple decorator. 
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Treatment of the Decimal Point and Decimal Digits 


In the result, the digits of a number's representation replace positions in 
the pauem's numeric field that contain digits. A decimal point can appear 
in the result only when it occurs as part of the pattem's numeric field 
Moreover, the fractional part of a number can be represented in the result 
only when the pallem contains both a decimal point and one or more digits 
to the right of it. 


When the pattem provides fewer positions for decimal digits than the rep- 
resentation requires, the representation is rounded at the right-most position 
provided. Thus, if you provide two decimal positions, а representation that 
requires more is rounded to the nearest hundredth. Similarly, if you use а 
pattem that makes no provision at all for decimals, the result is rounded to 
the nearest integer: 


ae'555,550 no decimals vs. 550.555" 
а on a 9 2/7415 


555,550 no decimals vs. 550.555 


1 no decimals vs. 1 
1 no decímals vs. 0. 
0 no decimals vs. 9. 
0 no decímals vs. 0. 
o no decimals vs. 0. 


Treatment of the Sign 


The sign is represented in the result by the controlled decorators in the 
pattem. Controlled decorator text can appear in the result in three ways: 
only for negative values, only for non-negative values, or for any values, 
regardless of sign. Controlled decorator text floats. 

‘The following are the digits that affect controlled decorator text. (For details 


and examples, see the description of the various following control digits, 
later in this section.) 


1 Include and float the controlled decorator text for a negative value. 


2 Include and float the controlled decorator text for a non-negative 
value. 


3 Include and float the controlled decorator text regardless of value. 


4 Block the effect of 1, 2, or 3 when interposed between them and 
а decorator text. 
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The following illustrates a decorator to mark negative values: 


a- on 05/05/05, balance vas (55,510.50)' 
а on a = 880611, 711 71 x2/23456.71 456.7 


On 05/05/05, balance was (55,510.50) 


On 88/06/11, balance was 23,456.71 
On 88/06/11, balance was (23,456.71) 
On 88/06/11, balance was 456.70 
On 88/06/11, balance was (456.70) 


A negative number can be represented in the result only when the pattem 
includes a controlled decorator text and the numeric field includes а 1 
(meaning "Include the controlled decorator when the value is negative"). 

When your paltem fails to provide for a negative value but w contains 
one, you have an overflow condition. The numeric field for that number is 
replaced by asterisks.” 


A negative value is marked in the result by whatever text you provide. 
‘There may be controlled decorator text on both sides of the numeric field, 
or only before or after. Note that if you want a leading macron as negative 
sign, you still have to say so explicitly; format by example does not have 
a default negative sign. 


Alternative Conventions Regarding Decimal Point and Grouping 


In the left argument of v, only a dot can indicate where the decimal point is 
to be located; only a comma can indicate a grouping symbol to be inserted 
between digits. However, different characters may appear in the result, 
in accordance with national convention. In the result, the character that 
separates integer from fraction is rel I: it replaces the dot that indicates 
the decimal point in the pallern. In the result, the character that separates 
groups of digits is Ofc(21; it replaces the commas that indicate grouping 
in the pattem. For example: 


26 Well, not quite only. You can represeat the magnitude of а negative value when the numeric field includes а Э, but since 
an coutobed west a den inched три, o siga. you have los dhe distinction bereeen negative ind dos eta 


27 Abemutively, depending on how you set Qfc[4), you may substitute some other character to indicare overflow of 0 
report а domain error. See the discussion of [17 с her in this section or in Chapter 11, "Syrien Nouns aod Verbs”. 
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Dfct1 21+", ' 
ae'555,555,555,550,5$5,555,555* 
а on a*,1.5*2x16 


555,555,555,550.555,555,555 


3,323 350 97 

52,342 777 785 

1 871,254 305 798 

119 292,461 994 609 

11 899 423,083 962 248 

1 710 542 068,319 573 16 


In the pattem, а dot indicates the decimal point when: 
. it precedes the бга digit or it is surrounded by digits in а numeric 
field 
and 
is the only such dot in the field. 


Thus, in the following pattem, the dot in 5.5 is the decimal point, but 
the sequence of three dots is simple decorator text (and reproduced in the 
result): 


а»!5,,,55.55' 
а ona 4 1Р 1 12.3 123.45 


Dot and Сотта 


The dot and comma are conventional decorators; they specify decimal digits 
or group separators according lo common conventions (as in 23,456.78). 


A comma is a grouping decorator when it is surrounded by digits in а 
numeric field. Thus, in the following pattem, the sequence 5,5 indicates 
where a grouping comma should be inserted. The other commas are not 
grouping commas because they are not surrounded by digits on both sides. 
In the result, a grouping comma appears wherever the result has a digit 
оп both sides of it. Other commas appear according to the usual rules for 
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decorator text. Thus the comma in Left, is not a grouping comma and 
neither arc the double commas. 


The phrase Left, and the right-most comma in the pattem are sign deco- 
rators; because of the number 2 in the picture, they are included (and float) 
for non-negative values. The word Right is not part of the sign decorator 
(since there is a space between it and the rest of the picture). Thus the 
double comma and the word Right appear in every field of the result. 


a- ert, 58. 528,5, Right! 
2345 712345 3 73 123 123 


Right 
Right 

1,,234,5, Right 
Left,,, 3, Right 
3 Right 
Left,,, 12,3, Right 

+e 12,3 Right 


A decimal point not followed by a numerical digit is a part of the trailing 
decorator and as such is included or excluded in the same way as any other 
part of the controlled decorator text. For example: 


а+'-5125.РО5* 
а on a #т123 123 


123. POS 
-123 


Significance of the Control Digits 0 to 9 
The control characters 0 to 9 are described bere in numerical order. 


0  Leadinglrailing zeros. Unused positions are filled with 0 from here to- 
wards the decimal point. For example: 
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255, 550.0055! 
aon a т 1 0 1000.1, +3 


55,580. 0055 


1f you do not specify any position at which а leading or trailing zero is 
printed, а zero value has no printed digits. The decimal point also turns 
into a blank when there is no digit to the right of it. 


а=" [555.55], 
а опат 4 1 1010.1 100 


[555.55] 
1 2 
t 3 
t 10.1] 
[1001 


1 Negative values. The controlled decorator texts next to the number's rep- 
resentation are included and йог! inward until they touch the number's 
outermost printing digits. However, when the valuc being represented is 
not negative, the controlled decorator is replaced by blanks. For example: 


aet Value (1550.50)* 
а on a 71.23 712.34 123.4 7123.4 


) 


Value 1.23 
Value (12.34) 
Value 123.40 
Value (123.40) 


2 Non-negative values. The controlled decorator texts next to the number's 
representation are included and float inward until they touch the number's 
outermost printing digits. However, when the number being represented is 
negative, the controlled decorator is replaced by blanks. For example: 
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3 


aet Value *2550.50Plus* 
a on a ¥71.23 712.34 123.4 7123.4 


Value +2550.50Plus 
Value *1.23Plus 
Value 12.34 
Value +123.40Plus 
Value 123.40 


Float. For all values, the controlled decorator texts next to the number's 
representation are included and float inward until they touch the number's 
outermost printing digits. (Notice that in the following example the result 
does not distinguish the sign of the argument.) 


ae'S5(35,550.55] 22! 
aon а ¥ 81.23 2 73333 .4 


Җ%[35,550.552% 


55181.23] 
1%0223% 
$x[3,333]33 
53(0.473* 


Two of the control characters 1, 2, and 3 may occur in the same pattern. 
(It is not illegal to put more than two, but since there are only two con- 
trolled decorator texts, left and right, only the outer two control characters 
are effective.) When there is more than a single occurrence of 1, 2, or 
3, inclusion of each decorator text is govemed by the control character 
encountered first, scanning from the decorator towards the numeric part of 
the pattem. For example, the pattem 


1+215550.500verdraft! 


causes + to be printed to the left of a non-negative value because, scanning 
from the left, 2 is the first relevant control character encountered. Similarly, 
Overdraft appears to the right of a negative value because, scanning from 
the right, 1 is the first relevant control character. 


The effects of the digits 1, 2, and 3 do not depend on where they are 
located with respect to the decimal point. 


No float, The action of a 1, 2, or 3 is nullified by a 4 that occurs between 
the 1, 2, or 3 and the decorator text. If the preceding example is modified 
by introducing а 4 somewhere to the right of the 3, the right decorator 
text is now reproduced in place for all values, but the left decorator text 
continues to float inward, as before: 
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a*'3X(35,550.55)3X KL 25, 450. 5514. 
a on a * 2/,81.23 2 3333 .4 


xx C25, 550. 55141 %%[35,540.541%: 


11181.23 4K %%[81.231%% 
35(223* 5502 PII 
NI, %%(3,333 295 
34%(0.4]%% 1200.4 1%% 


5 Normal digit. The position is available for a digit. If the representation of 
a particular value does not require the leading or trailing positions, the con- 
trolled decorator text moves in to occupy them (but only when a decorator 
text has been supplied and is controlled by the presence of a 1, 2, or 3 in 
the pattem). 


6 Field delimiter. The next rightward non-control character (thal is, any 
character other than 0123456789.,) starts a new field. This is needed 
where fields are not separated by blanks. The digit 6 provides an additional 
field break at the next non-control character. For example, this allows you 
to include slashes rather than blanks as field delimiters to format three 
integers (for example, to represent a date): 


"0556/06/05" ¥ 1988 11 4 
1988/11/04 


7 Exponential format, The value is represented in exponential notation. The 
next rightward non-control character (for example, e) separates the mantissa 
from the exponent, The decimal point (which must be somewhere to the 
left of the 7) marks the decimal point of the mantissa. 


Your pattem must provide al Jeast one digit to the left of the point. If a 
value to be formatted is negative, it needs another position for the sign. By 
convention, in scientific format the mantissa has exactly one digit to the left 
of the point and the exponent is adjusted accordingly. For example, 1988 is 
represented as 1.98863. To achieve that, usc 1 to mark the leading digit, 
with the character you are using as a negative sign to the left of it 


1t is possible to specify more than one digit to the left of the point. APL 
selects the exponent io match the number of digits to the left of the point. 
For example, when you provide two digits to the left of the point, APL 
selects an exponent that is a multiple of 2. If your paltem has three digits 
to the left of the point, APL provides an exponent that is a multiple of 3. 
This is the convention known as engineering format. Compare the left field 
(scientific) with the right field (engineering) in the following: 
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а+'71,75Е5 VS 155.785. 
a on a % 2/;10*0,\8 


8 “Check protection." Unused positions from here to the decimal point аге 
filled with the character specified in Q£c[31 (which by default ів +). 
4 559,555,535. 507 
a on a¥4 18123 12345 1234567 123456789 
$558,555,535.5 
541200 
$+***12,345.00 
$1,234,567.00 
$123,456,789.00 
9 Conditional zero-fill. Like positions marked by 0, these positions are filled 
with the character 0 when not otherwise used in the representation of a 
number. However, when the value being represented is zero, these posi- 
tions are left blank. In this fashion, an item whose value is 2сто may be 
represented by a blank field in the result. (Compare the following with the 
example for control digit 1, earlier.) 
a+t55,559,9955! 
aon a¥ 10 1234.1, 43 
55,559.9955 
1.00 
1,234.50 
0.3333 
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Effect of Ofc on * Format by Example 


The sysiem noun [fc is used as an implicit argument to ¥, affecting the 
result of its dyadic use with a character left argument. It contains six 
elements, which are used as follows: 


Dfct1J Decimal Character to separate the integer part from the frac- 
tional part of a number. Where the left argument & contains the 
character . used as a decimal point, the result of атш substitutes 
Ofcl1) for ., In a clear workspace, Ofc[1) is .. 


Ofcl2} Grouping. Character to separate groups of digits in the repro- 
sentation of a number. (The groupings are conventionally but 
not necessarily triplets.) Where the left argument d contains , 
surrounded on both sides by digits, the result of atw substitutes 
DfcL23. In a clear workspace, Ufcl2) is ,. 


ÜfcL31 Check protection or fill. Character to mark insignificant positions 
in the representation of a number. Where the left argument ч con- 
tains 8 and the corresponding digit in the result is not significant, 
the result substitutes Пёс[3]. In a clear workspace, Ofc[3] is 
*. 


Dfc(4) Field overflow. Character to indicate that the representation re- 
quires more space than has been specified in the left argument a. 
In the result, the entire field is replaced by Ofc[41. However, 
when D£c£4] is 0 and any of the numbers in w cannot be rep- 
resented in the space provided, the entire expression is rejected 
with a domain error. ln a clear workspace, Ofc[4] is . 

Dfc[5] Blank. Character to indicate where a blank should be substituted 
in the result, This is useful when you would like the result to have 
a blank within a numeric field or within a controlled decorator. 
Where the left argument a contains this character as a controlled 
character (that is, embedded within the positions devoted to the 
number's representation), the result contains а blank where the 
pattem contains Uf cl 5 J. In a clear workspace, D£c(51 ів _. 


Ofcl6] Negative Sign. This position is reserved for a character to indicate 
a negative value. However, at present the only permitted value is 
7, That is the value of Uf et 6) in a clear workspace. 
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$ 


Execute 


Only the monad 4 is defined. APL treats the character list (or ilem) w as a 
line to be executed, in the same way as a line in the definition of a verb, or 
a line entered from the keyboard, is executed. 


The argument w may contain only executable characters. in general, ex- 
ecutable characters are those enterable from the keyboard. (See “APL 
Character Set" in Chapter 3, “Nouns and Pronouns”) 


The result of аш is the result of evaluating the sentence represented by the 
character list t for example, 


2242 


ataedtat 
assigns the value 7 to the name A. 


The verb 1 permits an APL program to construct statements to be executed. 
Some uses of а are: 
< conditional execution 
» conversion of numeric constants 
passing unevaluated arguments to user-defined verbs. 
To illustrate conditional execution, consider processing a user's response to 
the question Proceed to execute Work? with а statement using 4: 
a(t Yes! 310) 9 work! 
‘The verb а can convert character lists representing numeric constants to 
their numeric values; for example: 
arati 23 


+/а 
6 


In this rather limited sense, а is inverse to ¥. (See also the discussion of 
Dfi and vi in Chapter 11, "System Nouns and Verbs") 


Since system commands are not APL statements, they cannot be executed 
by a; it follows that the first non-blank character in the argument of а 
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may not be ). Nor may а be used 10 invoke the V. editor, and so the first 
non blank character may not be V. 


The verb 4 can occur in the sentence that is the argument of 4, so thal the 
verb is used recursively. 


Result of aw 


Whether 4 has a result depends upon whether the sentence represented 
in ils argument, when evaluated, has a result. When it does, the result 
of evaluating the sentence becomes the result of а. Otherwise, а has no 
explicit result. For example, 

A!7142x110, 5xpv* 


retums a result. However, certain primitives have no result (for example, 
monad -, and system verbs such as Opdef or Ot i e). A user-defined verb 
may be written so that it docs not retum an explicit result. When the 
executed sentence has no explicit result, then the verb 4 has no result. For 
example: 

£'4 142x110. x 
[no result] 


A sentence that has a result can be embedded in a larger sentence; for 
example: 


1a 172 UO. 5xp vt 
A sentence that lacks a result cannot be embedded in a larger sentence: 
за'471+2х110,5хру! 
result error 


1à'47182xiL0.5xpvt 
^ 


The sentence 4* has no result. 


Display of Result 


When the verb 4 returns a result, the result is displayed if the result would 
normally be displayed; that is, 4% - 157 displays a value, but a- 
does not. 


Evaluation of Multiple Sentences 


The argument of а is treated in the same way as a line entered from the 
keyboard or within a user-defined verb. Thus, the argument may contain 
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several sentences delimited by the o character. Ii is also permissible to 
include a final comment to such a line, or an initial label. These are 
permitted on the principle that the domain of а should include anything 
that would be legitimate in the body of a user-defined verb. When the 
argument of £ contains а label or comment, both the label and the comment 
are ignored. 

Several sentences can be evaluated in a single use of 4 if they are included 
in the argument separated by diamonds; for example: 


ze Niob © х*у/\ру' 


"When the argument of + contains more than one sentence, the result retumed. 
by а is the value resulting from the last sentence evaluated. In the preceding 
example, x«y/1Py is the last sentence evaluated, and the value assigned to 
2 becomes the value of y/tPy in the same way as it would if the sentence 
were zexey/1Py. 


Occurrence in the State Indicator 


If а has been invoked but has not completed execution, it appears in the 
state indicator on a line of its own, in the same way as a user-defined verb. 
For example, when fn is a verb invoked by 4' £n* and its execution is 
suspended on line 3, then the state indicator appears as: 


281 
fn[3] * 
à 


In the sate indicator, a is represented by a line containing simply the 
symbol а. In Dc (the line counter), there is a corresponding item whose 
value is the line number of the line that invoked а. Similarly, in the table 
2 без 2, there is a row corresponding to a current use of а. (See the 
discussions of (1с and also Dws in Chapter 8, "Control of Execution"). 


Branch within Execute 


When a sentence evaluated by 4 contains а branch arrow, + the effect is 
the same as if the statement had been encountered as part of the defined 
verb nearest the top of the state indicator. 


لاه AU! шә sett фу‏ بي اداو 


If the value to the right of = is in the domain of +, the branch is taken. (See 
Chapter 8, Control of Execution”, for further discussion of branching.) 
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Errors Encountered During Execution 


When the sentence you try to execute contains an error, APL reports an 
error in the usual way. That includes generating an error message, a display 
of the offending sentence, and а caret io mark where in the statement it was 
working when it noticed the error. Execution is suspended on the sentence 
thai contains 4, not on the line which was the argument to а. However, 
the sentence displayed in the error message is the argument of а, not the 
sentence that invoked it. 

For example, suppose a user-defined verb called run contains on line 4 
the sentence xeAcommand. Suppose that, by the time APL gets to this 
statement, command is the name of the character list ' fix y'. But that 
is not an executable salement because fix has not been defined. 


In this case, rather than telling you that the error is on line 4 of run, APL 
shows the statement it is trying to execute (rather than the one that invoked 
a), thus: 
value error 
runl4)e fix y 

^ 


The 4 symbol is displayed in front of the sentence that has been asked. 
to execute. To clarify how the defective sentence was created, the display 
shows one 4 symbol for each level of invocation of а. For example, if the 
invoking sentence says 

xeacommand 
and the value of command was set by 

commande в' *?0*** 


the error message shows the execute symbol twice, like this: 


domain error 
run(4]44 ?0 
^ 


Osignai within Execute 


When signal w occurs within the argument of £, the effect is to abort 
execution of a and signal the event identified in o. The signal is sent io the 
environment in which «*Qsignal w1 occurred, Notice that the effect of 
a*Dsignal ©» is not the same as the effect of signa! w. They differ 
both in the activity aborted by signa! and the environment that receives 
the signal. 
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For example, when a user-defined verb foo contains the sentence (without 
4), 


Osignal w 


execution of foo is aborted, and event w is signaled to the sentence that 
invoked foo (and that is therefore next below it on the state indicator). 


But when foo contains the sentence 
s'Dsignal w' 


only 4 is aborted, The event w is signaled to the sentence that invoked è 
(that is, to the verb foo, which appears below a in the state indicator). 


Г 
Table, Ravel; Join 


Identity | Argument 


The monad , ravels (that is, relaxes the structure) of an existing array. The 
monad 7 forms any array info a table. As dyads, the verbs, (comma) and 
т (comma-bar) produce a single array by joining their two argument arrays. 


Monads , and > 


The expression , (“ravel 2") retums a list containing all the items of w in 
row major order. For example: 


T 
One Two Three 


The ravel of an item is а onc-element list. 


The expression о ("table 4°) retums а sable in which each row is the ravel 
of a major cell of w. For example, suppose X is a 2-by-3-by-5 array, thus: 
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x 
abcde 
fghij 
Inno 


parst 
uvwxy 
20123 
Then 7x is a 2-by-15 array as follows: 


тх 
abcdefghijklmno 
parstuvwxy20123 


Similarly, when w is a 2-by-3-by-4-by-5 array, то is a 2-by-60 table. 


The result of monad 7 always has rank 2 When w is a list, zw із a 
one-column table. When c is an ilem, z% is a 1-Ьу-1 table. 


Formally, ус is related to ,w by the identity 
w æ 071 0,9710 


in which the second occurrence of, #71 is needed only io cover the case 
when w is an item. 


Figure 5-11 illustrates the effect of т with the rank conjunction applied 
in various ways to а rank-S array. a is a 2-by-2-by-2-by-2-by-2 array. 
Successive sections of the figure show the result and the shape of the result 
for 75 and for 54. for 753. for 5*2, and for 71. The result of 20 a 
is not shown. It has shape 2 2 2 2 2 1 1, and does not fit conveniently 
оп a page, even in small type. 
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Figure 5-11 :Effect of monad v at ranks 5 through 1. 
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Dyads , and 7 
The dyad ато joins а and w along their major (that is, first) axis. The dyad 
0, 0 also joins two arrays, but along the Jast axis. Applied to tables, arw 
joins them vertically, while a , joins them horizontally. 
In general, the arrays thus joined must have the same rank. However, their 
ranks may differ by 1, or one of them may have rank 0. 


Dyad , is related to dyad 7 by the identities: 
سه‎ e» ar e RDW) 


Restrictions on the Domains of ; ог, 


The arrays being joined must be of the same type (character, number, or 
box). 


When both arguments are numeric but use different internal representa- 
tions for numbers (Boolean, integer, floating, or complex), the result has 
the intemal representation of whichever argument has the more extensive 
representation. 


When one of the arrays being joined is empty, the result has the type of 
the non-empty argument. When both arguments are empty, the result has 
the type of the right argument.* 


Shape of Arguments and Result 


The arrays being joined must have the samo length in all their axes except 
the axis along which they are to be joined. Arrays joined by ayw must 
have the same length in all axes except the first, and arrays joined by a, 0 
must have the same length in all axes except the last. 


If the arrays are not of the same rank, then either one of them must be a 
scalar, or of rank which differs from the other by one. If they differ by 
опе in rank, the array of lesser rank is treated as if it had length 1 along 
the axis of joining. If one is a scalar, it is treated as an array of the same 
shape as the other except along the axis of join, which is treated as length 


1. For example: 
+ a*2 3P'abcdef' 
abe 
def 
In principle, tbe type of — However, the typo becomes evident when an empty ariy i 
aber a- of ome e U r шиле Uu spy ыу iud бой э кту of 


botes is numeric.) 
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а, "ху 
abex 
dety 

а,2 le'xy* 
abcx 
defY 

aj XYZ' 
abc 
def 
xva 

arl 30K 
abc 
def 
XYZ 

apat 
abet 
def* 

aget 
abc 
def 
++ 


The result of av is an array for which the length of the first axis is the sum 
of the lengths of the first axes of a and w, and all other axes are unchanged. 
For example: 


be2 3p'uvwxyz* 
b 


Similarly, the length of the last axis of a „w is the sum of he lengths of the 
last axes of a and w. АШ other axes are unchanged. 


Pa,b 
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a,b 

abcuvw 

defxyz 

Figure 5—12 illustrates ways in which dyad 7 may be modified by the rank 
conjunction. The array a is the same as the a in the preceding figure, while 
A is an array of the same shape but containing capital letters. The default 
rank of 7 is infinite, so (for these rank-5 arrays) 7*5 is no different than 7. 
The effect of specifying rank 4, 3, or 2 is illustrated. (In each of the three 
parts of Figure 5—12, the first box shows the expression executed, the next 
shows the shape of the result, and the last shows the resulting array.) 


Using on-rank-4 yields а result whose fourth-from-last axis is the sum of 
the lengths of that axis in the arguments. Similarly, on-rank-3 affects the 
result’s third-from-last axis, and on-rank-2 affects the second-from-last. The 
same principle holds for on-rank-1 (see Figure 5-13.), but joining-rank-O 
produces a new axis in the result. 


Joining Two Arrays Along a New Axis 


When you join a and w along an axis that already exists, you are said to 
catenate them. When you join them along a new axis, you are said to 
laminate them. Catenate and laminate do not refer to different verbs, but 
to different contexts in which 7 or , are used. 


То join two arrays along a new axis, they must have the same shape or one 
must be a scalar. (That is consistent with the general rule that arrays being 
joined have to have the same length along each axis except the one along 
which they are joined.) 

Assuming that cells occupy the last axis, and all other axes are frame, you 
can make a new last axis by join-rank-0, thus: 


‘abe! ,90 N · 
ax 
by 
cz 


In general, when you join two same-shape arrays by ,¥0 or 720 (it does 
not matter which), the axes of the result are the (common) axes of с and 
©, followed by 2. 


There arc several ways to join two arrays along a new first axis. Both , 
and 7 create a new first axis when their arguments are items. Boxing the 
argumenis causes them to be treated as items. For example: 
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RO Vane Sane Gees 8K 


IE 


Гета А | аы 


ABCDEPGHIJRLNNOPQRSTUVWAY 


а 2 2 2 2P'abedefghi JR Tanopqratuvixyz. 


i 
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Figure 5- 12 ;Dyad x rank 4,3, and 2. 
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— —ͤ—ͤ— — 
[а тїї af |2 2 2 2 4| labas] 


Figure 5-13 : Dyad 7 rank 1. 


"abc! “< ‘xyz! 
abc 
xyz 
The above example applies « monadically to left and right cells. It then 
applies , to the results thus formed. Finally, the inverse of « (that is, >) is 
applied monadically to the results formed in the second step. 


Or, writing the same thing another way: 
> ‘abet э N 


abc 
xyz 
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Another approach is to increase the rank of one of the arguments before. 
you join them. For example, 


>,> w 


gives w a new first axis of length 1. (That is because <w is an item, „<w 
is the ravel of that item and hence has onc axis, and >, « keeps that new 
frame-axis when opened.) Then: 


"арс'т >,<' xyz! 
abc 
xyz 
‘The monad у tums а list into a one-column table. Applied to a list, that 
gives it a new last axis of length 1. If you then transpose il, the new axis 
is at the front, 


‘abet ar ‘xyz! 
abc 
xyz 


Joined Arrays May Differ in Rank by 1 


When one of the arrays has rank 1 less than that of the other, it is treated 
as if it had an extra. of length 1. The extra axis is a leading axis when 
the verb is т and a trailing axis when the verb is ,. For example, when 
you join a table and a list with 7, the list becomes a new row in the result; 
but when you join them with , it becomes а new column. For example: 


ar 'HIJ' 
abe 
def 
HIJ 


а,'12' 
abci 
def2 


Joining an Item to an Array 


When one of the arrays is an item (with no axes), the item is replicated 10 
match the lengths of all the axes other than the one along which joining 
occurs: 


ape 
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When both arguments are lists, the distinction between 7 and , vanishes, 
since, with only one axis, the first axis is the last axis: 


abe 
abcxyz 


* abc! „xyz 
abcxyz 

When both arguments are items, the result is a two-item list. (In this case 
the result has a new axis that was not present in either argument before.) 


Joining Modified by Bracket-Axis Notation 


Early APL systems permitted certain verbs to be modified by а number in 
brackets placed after the verb. Because the bracket notation is inconsistent 
with the rest of APL syntax, this is now regarded as archaic. Nevertheless, 
to permit existing programs to continue to work without modification, it is 
still supported in APL. The verbs, and у are among those that can be so 
modified. In the expression 

a,tk] w 
the value inside the brackets is a numeric item that identifies the axis along 
which the arguments are to be joined. Since it is an index, it is affected by 
the index origin Dio. With the axis explicitly identified, a, I. 190% has the 
same meaning эз tz 490. 
As usual, the arguments are required to have the same length along the 
axes other than the axis along which they are to be joined. To join а and 
w along axis 2, you write: 

а, [200 


To use bracket-axis notation to join along a new axis, you identify the new 
axis by a fraction that lies somewhere between the existing axis numbers. 
For example, to join along a new axis to be placed between axis 2 and 
axis 3, you could write а, 2. 590, To join along a new axis to be created 
ahead of the first axis, a, O. 5 10% In a O- origin context, the join could 
de written as a, 70.524). 


) Tbe friction does pot have to be 0.5; any fraction will do provided it differs by less than 1 from an existing axis number, 
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Reverse, Upset; Rotate, Rowel 


Identity | Argument 
Monad |Dyod | Element | Rank 


Reverse | Rotate 
Upset | Rowel 


The monads ө and $ reverse an array's major cells. The dyads ꝙ and © treat 
an array аз a collection of lists and rotale each list by an amount specified 
in the left argument. 


Monads e and ¢ 


Monad 6, called upset, reverses the order of the major cells; that is, those 
al successive positions along the first axis. For example, when t is a table 
with three rows, Өс upsets the order of rows: 


te3 59'One--Two--Three' 


t et 
one Three 
Two-- Two-- 
Three one 


Monad $, called reverse, reverses the order of the 1-cells; that is, those 
at successive positions along the last axis. Monad © upsets (tums upside 
down) the order of occurrence of an arrays major cells, There is a major 
cell corresponding to each distinct position along the first axis. In a table, 
the major cells are the rows of the table. Їп a rank-3 array, each major cell 
is a table. In a list, each major cell is an item. 


Fora rank-3 array m of shape 3-by-2-by-16, @m upsets the order of the three 
tables, but leaves the order within each table unchanged: 


өл 

сссссссссссссссс 

сссссссссссссссс 
bbbbbbbbbbbbbbbb bbbbbbbbbbbbbbbb 
BBBBBBBBBBBBBBBB BBBBBBBBBBBBBBBB 
сссссссссссссссс aaaaaaaaaaaaaaaa 
CCCCCCCCCCCCCCCC AAAAAAAAAAAAAAAA 
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In similar fashion, monad ф reverses the order of the 1-cells. The location 
of last-axis cells in a table is illustrated in Figure 5-14. 


Figure 5—14 -Reversing the order of a table's last-axis cells. 


In а rank-3 army, monad ф sill reverses cells formed by splitting each 
position along the last axis. Figure 5-15 shows reversal of the array formed 
by: 


є+2 3 5P'AppleAvianAxon BasinBeechBroom' 


Figure 5-15 :Reversing the order of last-axis cells in a rank-3 array. 


Dyads $ and e 


The dyads © and ө treat an array as a collection of tists. For each list in 
©, а contains a number indicating the amount by which that list is lo be 
rotated. The dyad ф, called rotate, rotates t-cells of w. It behaves as though 
it has right-argument rank 1. That is, it applies to lists spread along the last 
axis. Dyad 6, called rowel, does something similar, except that it applies 
to lists spread along the first axis. The symbols are chosen to suggest (at 
least for a table) the axis about which an array is rotated or reversed. 


Each dyad produces а result that has the same shape as ©, with each list 
al the same location in the overall array. However, within cach list, the 
sequence of items is rotated by an amount specified by an item in а which 
specifies by how much to rotale a list in w. 


а must be an array of integers. In general, it has rank 1 less than the rank 
of w, k must have the same shape аз © for all axes except the axis along 
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which rotation takes place, or must de an item. Since dyad Ф rotates the 
last axis, for ф, (Pa) must equal ~1+Pw, Similarly, since dyad ө rotates 
the first axis, for Ө, (Ра) must equal 1300. 


Each list being rotated is treated as а ring. It may be rotated any amount, 
any number of times, However, rotation by Pw simply brings the ring back 
to where it started, with no change. The effective amount of rotation is 
modulo the length of the list being rotated. For a seven-item list such as 
the following, rotation by 72 is the same as rotation by 5: 


726! abcdefg* 
fgabcde 


So abcdefg' 
fgabcde 


The dyads $ and © differ only in where in w they find the lists that they 
rotate, & rotates the 1-cells of c that is, lists spread over the last axis. Ө 
does the same thing, but to lists spread over the first axis. Applied to a 
rank-1 array, these are the same (since its first axis is also its last axis). 


The name rowel for aeu is chosen by analogy with the toothed gear that by 
rotating raises ot lowers a vertical bar. Applied to a table, dyadic © requires 
a left argument list containing an item for each column of w, Consider the 
following 7-by-20 table called Chart (shown horizontally double-spaced 
зо that the amount of rotation can be shown for each column): 


Chart 
kk ok * * 
LE E E] aa 


Each column can be rotated independently. For example: 


00112231072 100112 2 3 3 2echart 
* * . © Fae * * 
2 * ш . ЕВЕ * 
xR» oo 
3 2 E ee eo Be ke eee 
ВЕ... B Bg буз 
ecc... mna à Roose. ү 
een, ee Beers, 


5-94 Verbs 


February 1993 


SHARP APL Reference Manual 


In general, the left argument а must contain an item for each of the first- 
axis lists of w, so the shape of a is 10. However, when d contains a 
single item, it is applied to all the lists in w: 


let Tiet 
Two-- Three 
Three one-- 
one Two-- 
$ and e Modified by Bracket-Axis 


As monads, ф sad Ө are concemed with reversing cells identified by posi- 
tions along one axis (the last or the first). As dyads, @ and Ө are concemed 
with rotating each of a set of lists located at positions along one axis (the 
last or the first). Ф takes lists from the last axis, and Ө from the first. 


The ISO standard for APL permits you to identify some axis other than 
the first or last, by using brackets. Although bracket-axis notation is now 
considered obsolescent (because the rank conjunction perhaps combined 
with transpose now provides a more general and consistent way to achieve 
the same ends), to permit existing programs to run without modification, 
APL continues to support the use of brackets as a conjunction specifying 
the axis along which reversal or rotation take place, like this; 


а $Lk] w 

a өгк) w 
Since the axis of effect is expressly identified by the value in the brackets, 
there is no difference between GLK) and СКЈ. The value inside the 
brackets must be an integer item and must be a member of 1PPw (and 
therefore is dependent of the value of the system noun Oio). а must have 
rank 1 less than the rank of w and shape ( k#1PPW)/Pw. 

Upset and Rowel in Terms of Rotate and Reverse 

9 can be defined in terms of ф by the identities: 

we ow 


aes بے‎ a N 
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Transpose; Cant 


Identity | Argument 


The verb & permutes the order of the axes of an array. 


. The [ей argument of the dyad ot specifies how the axes are to be 
permuted, By your choice of left argument, you may also cause certain 
axes to be mapped together to take a diagonal slice through w. 

* The monad &w reverses the order of the axes of w. 

a e (OL PPW) BW 


When w is a list (having only onc axis) or an item (having no axes), the 
result of Be is a. 


Monad & 


When w is a table (rank-2), the result has rows where w has columns and 
columns where « has rows: 


ш we 
Copenhagen CLL 
Libreville oiu 
Luxembourg pbx 

ere 
nem 
hvb 
210 
giu 
elr 
neg 
‘The shape of the result of transpose is the reverse of the shape of ш, 
Раш e Po 


Thus, transposing a rank-3 array moves w's last axis (columns) so that it 
becomes the first axis (planes) of the result, When w is the 2-by-3-by-6 
array shown at the left, &o is the 6-by-3-by-2 array at the right: 
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© س‎ 
London LP 
Athens AP 
Ottawa ом 
Prague or 
Peking te 
Moscow to 
na 
hk 
ts 
dg 
ei 
ac 
ou 
nn 
wo 
ne 
89 


Dyad ® 


The dyadic form of & permits you to permute the axes of w or to map two 
or more axes together so as to select a diagonal section of w. 


a is a list of integers that tell APL what to do with each of the axes of w. a 
must contain one element for each axis of w. Transposition has no effect 
unless w has at least two axes, 


The positions within a correspond to the various axes of w. That is, position 
1 within a describes what is to be done with axis 1 of ш, and so on. 


The values within a refer to the axes of the result. Since axes are numbered 
starting from Ii o, the values in a must reflect the current index origin. 


The result can have any rank not greater than the rank of w, Suppose the 
desired result rank is called r. Then the numbers in a must be chosen such 
that а includes each member of vr al least once. For example, when you 
want a rank-3 result, 1 3 2 1 is a permissible value for a, whereas 1 4 
з 4 is not (because it omits 2). 


The result returned by aww is an array formed by permuting or mapping 
together the axes of ш. The result contains one axis for each unique number 
in а, When a contains no repetitions, the rank of the result is the same as 
the rank of ш. Suppose 2. c then: 


0 When w has ank 1, the system also accepts an йет for а where, strictly speaking, it should require а one element list. 
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pw + (Р2) [9] 
Pz <> (Sta When the items of a are distinct. 


Transpositions that Retain All the Axes 


When the numbers in a are distinct, all axes of w are included in the 
result; only their order is changed. Figure 5- l6illustrates how the axes 
are rearranged. 


س 8 2 4 31 


asofo 0 00 
ү] 
IN 1 4 2 
axes of result SON 
shape of w 2 1 3 -2 


shapeofresut 3 2 


Figure 5-16 :Axes of argument and axes of the result. 
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Suppose w has 4 axes. Then the expression 
3142 50 
says that axis 1 of w becomes axis 3 of the result; 
axis 2 of w becomes axis 1 of the result; 
axis 3 of & becomes axis 4 of the result; 
axis 4 of ш becomes axis 2 of the result. 
When а is a list of consecutive integers in ascending order, the axes are 
returned in the same positions they had before, and so: 


Фарри) ш e ш 


When the left argument contains consecutive integers in reverse order, the 
sequence of the axes of w is reversed, which is the same as the result of 
monadic transpose: 


{ф\ррш) بے‎ tw 


Figure 5-17 illustrates transposition with a specific example, using a rank-4 
array whose shape is 2-by-3-by-3-by-2, so that you can trace the relocation 
of the axes and of each of the items. 
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Figure 5-17 : Dyadic transpose of a rank-4 array. 
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Figure 5— 18 depicts « snd part of its transpose, showing how the бги plane 
of the first block of the result receives elements from w, w is depicicd as 
two blocks of tables, each containing three tables. 


Figure 5- 18: Visualization of a rank-4 array and its 3 1 4 2 transpose. 


Diagonal Slices 


"When a contains repetitions, the number of distinct numbers in а is less 
than the rank of w, во the rank of the result is also less than the rank of w. 
Consider what happens when w has rank 4, but a is 1 3 2 3, as in the 
examples in Figure 5-19 and Figure 5-20. The value 3 occurs both at 
position 2 and at position 4. Axis 3 of the result is to be formed from both 
axis 2 and axis 4 of w. Two distinct axes of w are mapped into a single 
axis of the result. 


Thai is done by taking an item from w only when its position is the same 
0n both axes. 
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13238% 


br 


3 


| 
boty 


ape of 2 3 3 2 
| A 

P4 

shape of result 2 3 2 


Figure 5— 19 :Axes mapped together during transpose. 


13 238 0 


Figure S- 20: Visualization of 1 3 2 3 transpose. 
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By mapping axes together, you are selecting a diagonal. For a 4-axis array 
w, the expression 


111189 
gives you the list formed by 
0[1;1;1;12, €[2;212;2], 3133 and so on. 


Similarly, for a table w, the transpose 1 1% gives you a list from the main 
diagonal, 


When the axes mapped together differ in length, the number of positions 
‘common to both axes is only as great as the length of the shortest axis. For 
example, when w has shape 3 10, the expression 1 140 selects only the 
elements that in Figure 5-21 are shown shaded. 


Figure 5-21 :А diagonal is confined to the length of the shorter axis. 


Figure 3-22 and the next two figures illustrate several types of diagonal 
slices taken from a rank-3 array. 
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axes of w О О О 


axes of result. 


shape ofw 2 3 4 


shape of result. 2 3 


Figure 5-23 : Mapping produced by 1 1 2 transpose of a rank-3 атау. 
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Figure S-24 :Mapping produced by 2 1 2 transpose of a rank-3 array. 


+ 
Raze; Take, Drop 


The monad + (raze) reconstitutes arrays by assembling the opened elements 
of the array along the leading axis. 


The dyads + (take) and + (drop) construct an array by selecting a segment 
along cach of the axes of w. The left argument a is a list that specifies for 
each axis of w the length of the segment to be selected. 


Monad + 


Raze opens each item along the leading axis of its argument, catenatcs 
those items along the first axis, and boxes them again. Raze is useful for 
reconstituting data thal were separated by the cuf conjunction. (See Chapter 
6, “Adverbs and Conjunctions” for the definition of cut.) Consider the word 
processing problem of replacing all occurrences of one word by another in 
a text vector. This might be achieved by cutting the text into words, boxing 
each word, finding the words of interest, replacing them, and then using 
Taze to paste the words back together into a vector: 
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"This and that and these and those. 


hs |land ||гһас {land {|these [land those. 
1 ا ا اجا اا ایی ے‎ 


Irhis [lor that Ilor 1lthese [lor ||those. | 
! = I 211 Wil l 


>эт 
This or that or these or those. 


When raze is applied to open arrays, the result is boxed as well: 


Fme3 50 fatsoocherbeets" 
fatso 
ocher 
beets 

+m 
(Ths ETT Hd 
1 fob] | acel] | hel Iset | tors} 
ttt 


When raze is applied to items, the result is the enclosed item. 
Operation along other axes can be achieved with the rank conjunction, 


Raze of Empty Arrays 


Because raze removes elements from the shape vector, it can create non- 
empty arrays from empty ones. If the leading axis of the argument is of 
length 0, the result of +w has shape 14, The result is filled with the box 
fili element. 


Raze Along Unit Axis 


Raze applied to an argument w that has length 1 along its leading axis pro~ 
duces a result of shape 14, formed by boxing each ilem in the argument. 


Dyad + and + 


The dyad tate describes the result by specifying the segments of w to be 
included in the result. The dyad drop specifies the segments of w to be 
excluded, so that the result is formed from those that remain. 
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The result always has the same rank as w (except when w is an item). Each 
value in а specifies the length of a segment along the corresponding axis 
of w to be included in or excluded from the result. For example, when w 
is а rank-3 array, the expression 
2 3 4 *® retums 
the first 2 positions along «^s first axis; 
the first 3 positions along w’s second axis; 
the first 4 positions along w's third axis. 
Drop works in a similar manner, except that it omits, ог drops, the specified 
number of items along each axis: 
2 3 4 + retums 
all but the first 2 positions along ш'в first axis; 
ali but the first 3 positions along w's second axis; 
all but the first 4 positions along w's third axis. 
А negative value in а refers to the fast positions along an axis. For example, 
the expression 
2734+ retums 
the first 2 positions along «^s first axis; 
the last 3 positions along «'s second axis; 
the first 4 positions along ws third axis. 
Again, drop behaves similarly to take with a negative values: 
2724+ retums 
all but the first 2 positions along «’s first axis; 
all but the last 3 positions along «^s second axis; 
all but the first 4 positions along «'s third axis. 
* а may contain fewer elements than the rank of «; in that case, degen- 
erate rules apply, described below. 
. a may never contain more elements than w has axes, except in the 
special case when c has no axes, discussed below. 


e a may be an item. In that case it is treated as though it were а one-item 
list. 


Sec Figure 5 -25 for examples of the operation of take and drop. 
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275 y 
result 
2 5 
-2 
5 result 
2 
2754 Y E 
"e result 


Figure 5-25 ; Take and drop. 


Take with Short Left Argument 


When а has fewer elements than w has axes, a describes how much to 
take of the leading axes of w, while the remaining axes are retumed enlire. 
Thus, for any array w have any rank 2 or higher, the phrase 
2 t retums 
the first 2 positions along 's first axis; 
the last 3 positions along w's second axis; 
all positions along any remaining axes. 
Similarly, the expression 2 ¢w retums 
the first 2 positions along ws first axis; 
ail positions along any remaining axes. 
And, by a logical progression, '' tw retums all of w. 
In general, the effect of а short lefi argument is: 


atw (a, (p, a) 70 ва 
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Drop with Short Left Argument 


When a has fewer elements than w has axes, а describes how much to 
drop from the leading axes of w, while the remaining axes are retumed 
without dropping anything. Thus, for an array © of any rank 2 or greater, 
the expression 
2 340 retums 
all but the first 2 positions along «'s first axis; 
all but the first 3 positions along w’s second axis; 
all positions along any remaining axes. 
Similarly, the expression 2 4% retums 
all but the first 2 positions along w’s first axis; 
all positions along any remaining axes. 
And by a logical progression ' ' +w retums w. 
In general, the effect of a short left argument is: 


aw c ((PPw)tajiw 


Dropping More Elements than Exist 


When а includes an element whose magnitude is greater than the length of 
the corresponding axis of w, you are in effect asking to drop more elements 
than exist along that axis. in the result, the length of that axis is 0; the 
excess value in a has no effect. Thus: 


рш 
46 

P3 26 
14 

P5 2+0 
04 


Over-Take and Padding 


When the magnitude of an element of a is greater than the length of the 
corresponding axis of w, you are in effect requesting to take from w more 
elements than exist along that axis. The result nevertheless contains as 
many positions as you request. The additional positions contain a fill value, 
which is: 


0 When w consists of numbers. 
hen € consists of characters. 
«10 when w consists of boxes. 
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Where an “oversize” element of a is positive, the result contains as many 
elements as are available in w, followed by the fill value for the remaining 
positions, so that the fill values (if any) appear at the end of that axis. 


Where an oversize element of is negative, elements are taken from the 
end of that axis of w and placed at the end of the corresponding axis in the 
result. The fill value appears in the extra positions at the front of that axis. 
Suppose w is the following 3-by-4 table of numbers: 


1 2 34 


ooooc 
ооооо 


Take When the Right Argument is Empty 


"When a calls for creation of a non-empty array but « is empty, the result 
contains only fill values. Then the result has the same intemal type аз the 
right argument? Although in general the type of an empty array is not 
significant, information regarding its type is retained and docs affect the. 
result produced by take (and also by the derived verb expand; все Chapter 
6, “Adverbs and Conjunctions"). 


‘Type of empty right argument: character Result: blanks. 
Туре of empty right argument: numeric Result: zeros. 


Take and Drop Applied to Item a 


When w is an item (having no axes), but a is not empty, APL treats w as 
if it had the rank implied by the length of a and every axis had length 1. 
Thus: 
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Take and Drop Modified by the Rank Conjunction 


Тре rank conjunction specifies the number of axes in an argument cell. Any 
leading axes left over are frame axes. When the rank conjunction modifies 
t, а applies not to w as a whole, but to each cell within w. Thus, the effect 
of the expression 

235120 
ів to take for each cell the first 2 positions along the cell's first axis and the 
first 3 positions along the cell's second axis. The frame axes are reproduced 
in the result. Thus, in general: 
(1. ) w ж» ((-k) + Pw),a) tw 


Similarly, whea k#0: 


(1, w e» ((-k)i0xpo),a) + ш 


When take is applied with rank 0, cach result cell has a new axis for cach 
item in a. In that case, the shape of the result is given by: 


patil 0 € «e» (Ро), la 
And the result is: 
atii Ow e ((e, |а)ри , % 1 (x/|u)PitOpu 
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A Y 


Grade up, Grade down 


Identity Argument 
Monad — Element. 
(Numbers) 
4 | Grade up — оо 00 09 
¥ | Grade down оо 00 0 


Grade retums a list of integers which if used to select the major cells of w 
would arrange them in order. The result has the same length as the first axis 
ofw, The argument must have at least one axis. The result is a permutation 
vector, since it contains each of the first 1* Pw integers exactly once. Since 
the values are indexes, the result is sensitive to Dio. 


The verb 4 retums the indexes that would arrange the major cells in ascend- 
ing order, while ¥ retums the indexes that would arrange them in descending 
order. Cells that have equal values are left in the order in which they occur 
inw. Thus, 4 and ff are said to be stable. 


Monads 4 and ¥ 


The monads 4 and ¥ are defined for real numbers. Complex numbers have 
по umambiguous sequence and hence are outside the domain, 


The dyads 4 and ¥ are defined only on characters. Characters have no 
inherent collating sequence, зо а describes the sequence to be used. 


The result of any of these verbs is the list of indexes that would sort the 
major cells of w. When w is a list, each major cell is an item, and the result 
of grade is the list of indexes that would sort the items. For example: 


List+1.2 1.1 1.2 1.4 1. 
AList 
25134 


List(áList) 
1.1 1.1 1.2 1.2 1.4 


List 
41325 


List(fList] 
1.4 1.2 1.2 1.1 1.1 
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When you grade an array that has more than one axis, the result is still 
a list of indexes for the major cells. The cells are graded by assigning to 
each cell а numeric value equal to the base value of all the items in the cell, 
taking them in ravel order (see the definition of , (ravel). ‘The base value is 
evaluated using а radix larger than the value of any of the individual items. 
Thai is equivalent to saying that the cells are graded so that the left-most 
item in the ravel of the cell has greatest weight, Por example: 


Table 

2 4 9 24 

2 0 0 18 

1.9 3 0 

17 7 6 
ATable 

1432 
Table[ATable;l 

1 4 9 2.1 

3 Uo 7 5 

1 9 3 0 

2 0 0 18 
Table[fTable;) 

2 0 0 1.8 

1 9 3 0 

17 7 6 

1 4 9 24 


Grade is Not Tolerant 


Grade is nos affected by Псї, comparison tolerance. This is because the 
monad grade depends upon the transitivity of greater or smaller, but tolerant 
comparisons are not transitive. 


Since grade is not tolerant, it is possible for grade to reverse the order of 
two cells even when the cells are reported as equal when compared by the 
tolerant relation = under non-zero values of Oct. 


Dyads 4 or ¥ Grade Character Arrays 


To grade character data, you must provide a collating sequence as the left 
argument of à or f. APL has no inherent collating sequence for characters. 
а assigns a numeric value to each of the characters in ш. With those values, 
the major cells are graded in the same way as a numeric array. 
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When the collating sequence t is a list, the value assigned to each character 
in w is d, so: 


афо e kaw 


When w contains a character that appears nowhere in d, it gets а value 
greater than the value of any of the characters that are present (just as d 
retums i o for an item of w that is not present in a). 


Alfe’ abcdefghijklmnopqrstuvwxyz' 


names 
jones 
baker 
jacobs 
james 

abel 


names(Alf&names;] 
abel 
baker 
Jacobs 
James 
Jones 


Collating Sequence with Tied Weights 


When the material to be sorted contains both lowercase letters and capitals, 
what is to be done? Schemes such as A1 £1 and A1£2 include both but do 
not lead to satisfactory alphabetization. (See Figure 5-26.) 


The heart of the matter is that a one axis alphabet such as AIF has no 
way to give two characters the same weight. There із no way to put two 
characters at the same position. The problem is solved by using as many 
axes as necessary to accommodate sets of characters that are tied. 


Suppose you want to place b and B after a or A and before c or C. А 
simple way to achieve the desired sort is to use a collating sequence with 
two axes, such as Al £3: 


yA 
* abcdefghijklmnopqrstuvwxyz 
* ABCDEFGHIJKLMNOPQRSTUVWXYZ 


(The * is there so you can see that the first position is blank.) 


Where a has more than one axis, the dominant consideration is the position 
м which a character is found along the fast axis of a. (In a table, which 
column it is in.) In A1£3, both b and B are at column 3. 
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AÍfl 
abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ 
Alf2 
AAbBCCdDeEf FgGhHiIjJkKlLmMnNoOpPqQrRsSt TUUVVWWXXY YzZ 
Alf3 
abcdefghíjklmnopqrstuvwxyz 
ABCDEFGHIJKLMNOPQRSTUVWXYZ 
Ант raiden) eLAleshes) 
Ала 
YMCA 
Trudgen 
Tektite 
pi enbolicm 
stroke pavilion АМА ammonia 
pavilion phosphate DPD DPD 
piping photosynthesis embolism embolism 
respiration pi NSPF NSPF 
pump piping pavilion pavilion 
photosynthesis | plug phosphate pH 
underwater pool photosynthesis Philodendron 
tsunami porosity pH phosphate 
pool pump pi photosynthesis 
NSPF pH piping рі 
| recovery recovery plug piping 
: uni nun respíration pool plug 
embolism stroke porosity pool 
| pug trudgen pump porosity 
Tsunami tsunami Philodendron pump 
trudgen underwater recovery recovery 
pH Ama respiration respiration 
porosity AMA stroke stroke 
phosphate DPD trudgen Tektite 
DPD NSPF tsunami trudgen 
| | ammonia Phílodendron Tektite Trudgen 
AMA Tektite Trudgen tsunami 
Philodendron Trudgen Tsunami Tsunami 
acid Tsunami underwater underwater 
ana YMCA YMCA YMCA 


Figure 5-26: Effects of alternative left arguments to grade. 
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A character's location on the other axes contributes to the result only to 
break a tie between words that otherwise would have the same weight. The 
next-to-last axis breaks a tic on the last axis; the axis before that breaks a 
tie on the last two, and so on. To see the effect of this rule, compare the 
ordering produced by the tabular alphabet А! £3 with the ordering produced 
by the single axis alphabet A1f1. The list of words to be ordered is 
taken from the paper by Howard J. Smith, who first proposed the rules for 
alphabetic grade." 


Characters with Identical Weights 


The table A1£3 provides that b or B comes after а or A and before c ог 
C. Wherever there is а tie, a word that contains b always precedes a word 
that contains В. However, it is possible to construct the left argument so 
that certain letters have identical weights, and thus words that differ only 
in those letters are unaffected by grading. 


For two characters to have identical weight, they must have the same effec- 
tive position in а. When the same character occurs at two or more positions 
in a, that character 's effective position is at the minimum of its various co- 
ordinates. For example, if the letter 5 occurs at row 1, column 40 and also 
at row 5, column 13, then its effective position is 1 40L5 13; that is, row 
1, column 13. The letter 5 then has identical weight to а unique character 
located al row 1, column 13, of 10 to any character that occurs twice, both 
in row 1 and a higher row, and in column 13 and a higher column. 


To give capital and lowercase letters identical weight in sorting, one se — 
(for example, the lowercase letters) is usually placed at the top left corner 
of the alphabet table, while the other set is duplicated, both to the right ang 
below, as illustrated below. 


abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWYXZ 
ABCDEFGHIJKLMNOPORSTUVWXYZ | 


In such a table, the effective weight of a is exactly the same as the effective — 
weight of A. See Figure 5-27. 


n HL J, Smith Ir, “Sorting: а New/old Problem”, Proceedings of АРІЛ9, APL Quote Quad, vol. 9, 00. 4. | 
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Тыны 


ese al pin pois 
to the same diagonal 


Figure 5-27 : Effective weight of characters occurring twice in a. 


р 
Shape; Reshape 
1 The symbol P (rho) denotes the verbs shape ot reshape. 
» The monad ро returns the shape of w. 
. The dyad apo (“а reshape of 0) creates an amy whose shape is û 
and whose items are taken from w. 
! Monad р 


‘The monad Pu (“shape of ©") returns the length of each of the axes of w. 
The result is a list of (non-negative) integers. Since it contains one element 
for each axis of w, the number of elements retumed tells you the rank of 
ао, The value of each element is the length of the corresponding axis of w. 
When w has no axes, the result is a list containing no items (an empty list). 


For example: 
2 3016 
ро 

23 
ppw 
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15 


[Empty list displays as blank line.] 


ppw 


Dyad р 


The left argument а is а list of non-negative integers specifying the length 
that each axis is to have in the resulting array. APL accepts an item as 
equivalent to a one-element list, 


The right argument w is an array of any type or shape, However, w may 
be an empty array only when the new array is empty also (that is, when a 
contains a zero). APL rejects an attempt to create a non-empty array from 
an empty array with the message length error. 


The expression арш retums an array whose shape is a and whose items 
come from «. The posilions in the result are filled by taking the elements 
of w in row-major order. Row-major order describes the sequence in which 
items in an array are considered. Referring to a table, it means that you 
take all the items in the first row before you go on to the next row. More 
generally, for an array of any rank, you step through the positions along 
the last axis, then along the next to last, and so on. This is the same order 
as produced by the APL verb ravel, so that: 


арш = арш 
In apc when а asks for fewer items than there are in w, items are taken 
from @ in row-major order until the result is complete; any remaining items 
of w are ignored. 
When a asks for more items than there are in o the items of w (always in 


row-major order) are repeated cyclically in the result. For example, suppose 
w is a 2-by-5 table containing the following values: 


01234 
56789 


Then a result containing fewer items than w might be obtained as follows: 


5-118 Verbs February 1993 


SHARP APL Reference Manual 


TP 
0123456 


Or by: 


result requiring more items than there are їп w might be obtained as 
follows: 


120€ 
012345678901 


Or by: 


Note that if а is a list longer than Pw but ending in Ро, the effect is to 
replicate « completely at each of the positions along the new axes. For 
example: 


рш 


012234 
56789 


If the shape of the result differs from the shape of the right argument, a 
systematic pattem may be generated. For example: 


ооо» 
cono 
oroo 
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The shape of a single йет (a scalar) is empty. To generate an item with 
dyad Р, the left argument а must be empty? 


(10)рш 


The shape of the result produced by reshape matches the value of а. The 
only exception is that APL tolerates a scalar а for а one-clement vector. 
Thus: 


рари a 
and 


(Pwjpw ж» w 


€ 
Member 


Identity Argument 


For each item (that is, each number, character, or box) within a, the ex- 
pression aew reports whether а matching item can be found anywhere in 
ш. The shape of w does not matier, nor does the position in w at which a 
matching item is found. 


‘The result is a Boolean array having the same shape as a, with a 1 for each 
item in а that is matched somewhere in w, and a 0 for each item that is 
not. 


Liste2 3 5 
+Tables2 3012 34 5 6 


123 
456 


2 є List 


List € Table 
111 


Table € List 
EK 
010 


* For most purposes, the type of an empty array is immaterial, зо * * Ры works equally well. 
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Items with different levels of boxing never match. For example, if you ask 
whether the numbers in the open list 1 2 3 are members of an array of 
boxes, the answer is “no” even when those values are inside the boxes: 


123 (1 2 3 4),«'abcd* 
000 


Similarly, a singly enclosed box is not a member of a doubly enclosed box: 


(Habe), def“) є (««'abc*),««'def* 
00 


Membership Modified by the Rank Conjunction 
The rank conjunction ¥ may organize the frame in which membership in 
a cell of w is retumed. For example, suppose п is a seven-item list of 
numbers and T is а nine-row table. (li does not matier how many columns 
Thas) Then 


n 
69354962 
т 


له ج مم مم ې ت نم ت ب 
тоо‏ دد فاد تت 
ve e‏ دري ي س ت о‏ 


ner 
0111110 


retums a result-frame of rank I. Within that frame, there are seven cells, 
each containing a 1 or a 0, showing whether an element of n exists some- 


where in 7. 
By contrast, 
neler 
0001000 
0000010 
0000010 
0001000 
0010010 
0000010 


February 1993 Verbs 5-121 


SHARP APL Reference Manual 


0010000 
0000100 
0100100 


says you should consider гапк-1 cells from both arguments. For n, that 
means the entire array is а single cell, so n has an empty frame. 


For 7, that means each row is а cell. There is a frame axis of length 9 (that 
is, the number of rows that T has). 


Since one argument has an empty frame and the other has a length-9 frame, 
the result has а length-9 frame. As usual, the empty frame is paired with 
each of the cells in the other argument. So the first cell of the result is 
formed from пєТ[1;], the second from neT[2;], and so on. Each of 
those produces a sever-item cell. The cells fit into the length-9 frame, so 
the result has shape 9-by-7. 


Є 
Find, In 


Identity 
Monad | Dyad | Element 


[поле] | Find: in | [none] | # о 


‘Argument 
Rank 


m 


Dyad € 


The dyad є (in, also known as string search or find) locates all occurrences 
of one array within another. For an array w and a pattem array a, the 
statement 


beaeu 


produces a Boolean array b such that the Is in b mark the beginning points 
of the pattem a in w. The beginning points are the first element of a list, the 
upper left-hand comer of a table, and so on for higher-dimension arrays. 
The array b has the same shape as ш. Both a and w can be arrays of any 
rank. 


1n can be defined in terms of the 3-cut of “A Dictionary of APL” as follows: 
аво = ((W1, To) 39«u)e«a 


In can be used in string searching as follows: 
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'to'£'Onto Toronto, pronto,Tontol* 
001000000010000000100000100 


In can be used to remove multiple blanks from a string T using the expres- 
sion ( '&Т)/Т. 


In can be used for pattem finding in higher-rank arrays аз well, lending 
itself to image analysis and similar applications: 


pat -2 30123234 


ES 
we 
ew 


timagesS 3014 


Pewee 
Me M 
wres w 


COCO Oy Rw NE 


oooocn 
e-ooo 
S 


Identity | Argument 


The symbol 1 is the Greek letter iota. Monad 1 generates consecutive 
integers. Dyad \ retums index numbers: that is, the locations in a at which 
the items of ш are found. 
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Monad 1 


The monad 1 “counts” in the sense that n retums a list of the first n 
integers. The first counting number ìs either 1 or O, as set by the system 
noun Dio, index origin. 


15 4010-1 
12345 


15 4010.0 
01234 


Moreover, for a list I, 
10 
is the index for each of the items in L, so that 


L e» LOPL) 


Default Rank of Monad 1 


Monad 1 expects a single integer as its argument. И you impose argument 
rank-0, you can generate several sets of consecutive integers. 

For consistency with existing applications, APL treats monad 1 as though its 
usual argument is a list, even though that list may only contain one number. 
Having a rank-1 argument is handy in expressions such as АС10В]. 


Forcing argument rank-0 permits a table result, thus: 


But it also gives a table result in contexts where you may not want it, for 
example to generate a list of indexes. 


Dyad 1 


Dyad \ (indexof) maps the value of each item in w to an index that identifies 
a location in а. The expression aiw retums a result that indicates where 
in the list a each of the items of w may be found. For example: 


a- abcdefghijkimnopqrstuvwxyz' 
an cat 
31 20 
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«о may be of any rank or shape. The result has the same rank and shape as 
4. For example: 


ob 


atb 
6 120 
3 120 


а must be a list, so that a single index is sufficient to identify a location 
within а, 
The result is dependent on Dio. For example: 


altcat' 4 Qioel 
3120 


av'cat! 4 010+0 
2019 


For an item in w that does not occur in a, indexof retums Піо+Ро. 


For an item in w that occurs more than once in a, indexof retums the 
index of its first occurrence in , This is exploited in a common phrase for 
computing the nub (that is, the unique members) of a list: 


((QUPLÍst)-ListiList)/List 


For an item that is duplicated in List, the first occurrence has an index 
equal to its position. However, later occurrences also have that same in- 
dex, which therefore must be different from the corresponding member of 
1PList, resulting in their exclusion from the nub. Nub can be more tersely 
defined using nubsieve, as (o) /u, 


Tolerant Comparison in Dyad + 


The expression aw asks, in effect, for the index of the first item in a that 
maiches an item in w. Match is affected by comparison tolerance, Oct. 
Strictly speaking, indexof retums the first location in а that is tolerantly 
equal to an item in w. (See the discussion of tolerant comparison in the 
description of = earlier in this chapter.) 


‘Comparison tolerance can have no effect on the result of indexof or mem- 
bership when the arguments are characters or integers in the range -2% to 
21-1. However, it may indeed affect both the results and the time required 
to compute them for fractional or complex values. 
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a [o] 


Bracket indexing 


The expression (or expressions) enclosed in square brackets selects ilems 
from within the noun u, which may be any array having at least one axis. 


Bracket indexing is anomalous in several respects. Unlike other APL verbs, 
indexing is indicated not by a single symbol but by a pair of symbols. In 
some respects the left bracket С is the primary symbol, while the right 
bracket J serves to delimit the right argument. Delimiting the argument 
implies an order of execution, like putting parentheses around the entire 
indexed expression: 

ali) +b es (aU) +b 


The brackets surround not an expression but a set of independent expres- 
sions, one for each axis of а, To select from an array whose rank is greater 
than 1 requires more than one index expression; the various expressions are 
separated from each other by semicolons. When а із a list, one expression 
suffices to specify positions within it. This is written: 


apu] 


When о is а list, bracket indexing is inverse to dyadic iota. For an апау x 
(of any rank) all of whose items are contained somewhere in a: 


x «ә ata] 


However, when а is an array of rank 2 or greater, using bracket indexing 
to select а sub-array from within it requires a separate expression for each 
of a's axes. These expressions are separated by semicolons, and the set of 
expressions for all of a's axes is surrounded by brackets. The number of 
semicolons is therefore one less than the rank of с. For example: 


When a із a table: alu; 45] 
When а has rank 4: або; 6i 1 44 


Figure 5-28 illustrates the use of bracket indexing to select an item from 
an array. 
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result [7] 


Figure 5—28 : Expression to select an item from a rank-3 array. 


Shape of the Result Produced by Bracket Indexing 


The result of aCe} рш j... is an aray formed by selecting items from а 
at the positions indicated by the values in w,, ú, etc. Each of the index 
expressions a ... ш, may be of any rank or shape, provided only that every 
one of its elements is a valid position within the corresponding axis of а 
(subject to the visible value of the index origin Oto). The shape of the 
resulting array is found by calenaling the shapes of the indexes for each 
axis; that is: 
palê . P 1 ж» (Рад), (Р), . . ( 


The symbol ; is punctuation. К is a delimiter, not a verb. Wriling un zen 
does not form a single атау from w, and a}. You cannot write a general 
expression such as [ш] that will be valid regardless of the rank of d. In 
fact, alw) is valid only when a is а list (since it contains zero semicolons), 
and a[n рш] is valid only when a is a table (because it contains one 
semicolon), and so on. The semicolon acts as an absolute separalor in 
these expressions, so you do not need to enclose the various expressions 
for cach axis in parentheses (even when they are compound expressions). 


To write a program that can index an array of any rank, you must either 
generate a character expression containing the correct number of brackets 
and semicolons and then execute it with 4, or else index it by referring 
always to the ravel of the array, exploiting an identity mentioned below. 


Keeping All Positions Along an Axis 
You can retain aif positions along a particular axis of a by not selecting 
along that axis. You do that by writing no expression for that axis at 
the appropriate position between brackets, That axis is then reproduced 
unchanged in the result. 
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For example, when a is a list, the result of aC] is a. 


When а has three axes, then u Lc 50 ; indicates that, along the first axis, 
positions are to be selected by «л; along the second axis by «5; but the last 
axis (for which no index has been specifed) is to be reproduced completely 
in the result. Similarly: 
агі 23] selects positions | and 2 (subject to Ii о) from the first axis (rows) 
and ай positions from the second axis (columns) 
а[;1 2) selects all positions along the first axis, and positions 1 and 2 
(subject to D10) along the second axis. 
For any axis i for which no ш, is stated, the shape is (pa) Ci]. 
The elements selected from a are those whose positions are described by 
all possible combinations of the first-axis indexes mentioned іл w, with the 


second-axis indexes mentioned in w, and so on for all the axes. See Figure 
5-29. 


w w[12; 13; 24] 


nn 
L 


Figure 5-29. Expression to select a sub-array from a rank-3 атау. 
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Where an axis is indexed by an item (which has ло axis), the corresponding 
axis is omitted from the result. For example, when a is a list, a(2) retums 
an item with no axes because 2 is an ilem with no axes. See Figure 5-30. 


Similarly, when a is a table, а[1 3 52 retums a three-element list, 
whereas a1 3 55,27 retums a 3-Бу-1 table, 


w 4111 1 3; 4 2 51 


Figure 5-30 : Indexing an axis by an item removes that axis from the result. 


‘When any of the selection arrays is present but empty (for example 
alw, ;9,] when ш, is an empty array), the corresponding axis is present in 
the result, but has length 0. 


Indexed Assignment 


А bracket expression (0,565; . 10% may appear to the left of the 
copula. (Sec the discussion of indexed assignment in Chapter 4, "Naming 
Nouns and Pronouns”.) Such an expression has the form: 
alih; . Wylex 

Within the brackets, you must have a valid index expression ot several such. 
expressions separated by semicolons, depending on the rank of d. The 
requirements for a valid list of indexes are the same as for indexed selection. 
‘The expressions inside the brackets imply the shape of a sub-array within 
а whose elements are to be respecified. The indexes for respecification 
determine the shape of the sub-array in the same way as the indexes of 
indexed selection, described in the preceding section. This is also the shape 
of the result received by any other verb to the left of: 


alwa ... 1% -x. 


The shape of the right argument usually must match the shape implied by 
the indexes. However, the shape of the right argument is acceptable 
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if it matches the implied length of each axis having a length other than 
1. For example, if the implied shape is 2 3, then w could have shape 2 
3, or w could have shape 1 2 3 or 2 1 3. or 1 2 1 1 3 1, and so 
on. Similarly, when the implied shape is 2 1 3, the shape of w would 
be acceptable if it were 2 3, or 1 2 3, and so on. Those axes of w 
whose lengths are not 1 must have the lengihs implied by the various index 
expressions within the brackets. 


When w is an item (or onc-item array of any rank), APL reshapes it lo 
match the implied shape. 


Effect of Indexed Assignment 


APL replaces the indicated positions within a with the values of the core- 
sponding elements of w. 


2 3 40124 


9 10 11 12 


13 14 15 16 
17 18 19 20 
21 22 23 24 


Fb2*2 2P101 102 103 104 
101 102 
103 104 


Fb 23331 4) 
9 12 
21 24 


Fb(1 23351 4]+Ь2 
101 102 
103 104 


5-130 
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The values inserted must be of the same type (character, numeric, or box) 
аз the array into which they are inserted. For numeric arrays, the inserted 
values may differ from a in their intemal representation (Boolean, integer, 
floaling, or complex). In that case, the entire array а is converted to the 
intemal type required to accommodate the new elements. This affects the 
space required to store a. For example, inserting an integer other than 1 
or 0 into a Boolean array causes the entire array to be converted to integer 
internal representation, requiring 32 bits per item rather than one bit per 
item. 


In the case where the indexes contain duplicate values, the right-most value. 
is used. For example: 


vidlavia 4 41*1 2 3 
3 


Explicit Result of Indexed Assignment 
A sentence may make immediate use of the result of an indexed assignment, 
perhaps like this: 
21121 


The result of indexed assignment (like the result of assignment generally) is 
о, and not the merged new value of a. For further discussion, see Chapter 
4, "Naming Nouns and Pronouns”. 
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6 Adverbs and Conjunctions 


An adverb modifies the definition of a verb or creates a verb from a noun. 
A conjunction modifies the definition of а pair of verbs, or a verb and 
a noun. The modification takes place before the verb is executed; what 
is executed is the modified verb that the adverb or conjunction produces, 
called the derived verb. 


Adverb Each of the symbols # x / and \ denotes an adverb. An 
adverb modifies a single verb or noun. The adverb symbol 
follows the symbol for the noun or verb il modifies. 


Conjunction Each of the symbols . " * and Б denotes a conjunction. 
A conjunction joins two verbs to form a new derived verb, 
ог joins а noun and a verb. The verbs that cach adverb or 
conjunction can modify аге noted in their descriptions, later 
in this chapter. 

An adverb or conjunction can modify a primitive verb. This chapter opens 

with a summary of general characteristics of adverbs and conjunctions, and 

then describes each of the primitive adverbs and conjunctions individually. 


Precedence of Adverbs and Conjunctions 


APL has one rule of precedence: 
* Adverbs and conjunctions are evaluated before verbs. 


All adverbs and conjunctions have equal precedence (just as, among verbs, 
all verbs have equal precedence). You have to know what derived verb 
эп adverb or conjunction produces before you can parse the rest of the 
sentence. Therefore, as you read a sentence from left to right, whenever 
you come to an adverb of conjunction, you evaluate й at once, and replace 
it and its arguments with the resulting derived verb. 

You treat an adverb or conjunction differently from a verb in the following 
respects: 

. When you come to an adverb or a conjunction, evaluate it at once. 

« When you come to an unmodified verb, delay evaluation until you 
know the value of its right argument. (You do not have to delay for 
the left argument: because you are reading from left to right, you 
already know what that is.) 
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Valence of Adverbs and Conjunctions 
An adverb is a monad. h applies to the noun or verb to its left. 


А conjunction is а dyad. It applies to the verbs (or the noun and verb) on 
each side of it. 


Syntactic Class of the Arguments to an Adverb or Con- 
junction 


The effect of an adverb or conjunction depends upon whether its arguments 
are nouns or verbs — that is, on the syntactic class of its arguments. See 
the section “Syntactic Classes" in Chapter 2, “Grammar”. 


. For each adverb there are two possible meanings, depending upon 
whether the argument is a noun or a verb. 

» Foreach conjunction there аге four possible meanings, depending upon 
whether each of the arguments is а noun or a verb. 


For most adverbs and conjunctions there is a generic name for the symbol 
(applicable to all the cases) and specific names for the separate meanings 
that depend on the valence of the arguments. 


Ambivalence of the Derived Verb 


Once an adverb or conjunction has produced a derived verb, you can use. 
the derived verb either dyadically or monadically. The dyad and the monad 
are sometimes given distinct names, depending on the effects they produce. 
The various names are noted as part of the description of each adverb and 
conjunction, 


Consecutive Adverbs and Conjunctions 


In principle, а sentence may contain a sequence of several adverbs and 
conjunctions in succession; “A Dictionary of APL” contains numerous ex- 
amples. The first adverb modifies a verb to produce a derived verb, which 
in turn is modified by the next adverb, and so on. Currently, an adverb or 
conjunction in APL can apply only to а primitive verb, not to a derived 
verb, and therefore cannot occur in a sequence such as +.х/. 


0 In APL the moun-poun case does not occur, although it does in “A Dictionary of APL.” 
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Example to Illustrate Order of Evaluation 


Here is an example that mixes some verbs that are not modified by adverbs 
or conjunctions with some that are, Assume that the names А, B, and C 
refer to nouns. In the diagrams to the right, a dotted enclosure surrounds 
an area still to be examined, while а solid box encloses а derived verb. 


С-Ах#2-В+2 


Reading from left to right, the. 
first verb is subtract. Since 
the verb — is not modified by 
an adverb or в conjunction, it 
is an ordinary verb. Set it 
aside until you know what its 
right argument is. 

‘The next verb is x, which is 
modified by b. the rank con- 
junction. Evaluate the con- C - 
junction at once. Ils argu- 
ments are the verb x on its left 

and the number 2 on its right. 

‘That gives you the derived 

verb х2, read as "times-rank- 

2" The derived verb x is 

not modified by another con- 
junction, but you cannot exe- 
cute it yet because you do not 

yet know the value of its ar- 
gument. Set it aside until its 
argument is known. 

The next verb is . Since it 

is not modified by an adverb 

or conjunction, it із an ordi- С - 
пагу verb. Set it aside until 

you know what its right argu- 
ment is. 

The next verb is +. It is not 
modified. You know the value 

of its right argument. Evalu- С - 
ate it. Replace +2 with the 
resulting noun. 


7 Н 
A |2 | -Be2 | 
— 1 
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Now you know the value of 
the right argument of the — 
that you set aside two steps 
ago. Go back and evaluate it. 
It has no left argument, since 
to its left there is a verb (the 
derived verb x2). 

Replace the segment -noun 
with the resulting noun. 


Now you know the value of 
the right argument of the de- 
rived verb x92. Evaluate the H 
derived verb. Replace Ах22- 
B42 with the resulting noun. 
Now you know the value of : 
the right argument of the - : noun 
you set aside earlier. Go back i 

and evaluate it. It is the root 

verb. The sentence has been 
completely evaluated, and the 
remaining noun is the result. 


noun 


Look-Ahead 


Reading from left to right requires you to look ahead, Each time you come 
to a noun ог verb, you have to check whether it is modified by an adverb 
or conjunction. You do not have to look far ahead: if there is a modifier, 
it must be the next thing to the right. Whenever you discover that what is 
to the right is а noun or verb, that is sufficient to show that your current 
noun or verb is not modified. 


Separating Side-by-Side Constants 


Because adverbs and conjunctions have higher precedence than verbs, two 
nouns may appear side-by-side in а sentence. This happens when both the 
argument of а conjunction, and the argument of the resulting derived verb 
are nouns. For example, if you want to find the rank- product of an array 
A and another array X, you write: 


А xên X 
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That sentence is perfectly acceptable. But suppose you know that in a 
particular case п із 1 and that X is simply the numbers 4 5 6, and you 
choose to write those values as constants. The blank, which serves to 
separate the name n from the name X, cannot be used to separate the 
number 1 from the number 4 5 6. If you were to write 


Axl 45 6 

or even. 
А x91 456 

the numbers would run together to form the single noun 
1456 

Here are some ways to make plain what you intend: 


А 4 5 6 Use + to separate the two noun constants. (The verb 
+ retums the argument to the right without changing 
it. Из presence makes clear that 1 and 4 5 6 are 


separate nouns.) 

A жё164 5 6) Ры parentheses around the derived verb's right argu- 
ment. 

А xF(1)4 5 6 Ры parentheses around the conjunction's right argu- 
ment. 


| Although “A Dictionary of APL allows parentheses around the derived verb, for example AC х1 )4 5 6, they wm not 
‘curently permitted in APL. ug D m 
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Adverbs 

yz у/ш n/W n/w 
Reduction, Replicate, Compress 

viw y NO nNO n NO 
Scan, Expand 


These four adverbs produce a family of derived verbs with the following 
things in common: 


Right rank Each has unlimited right rank, That is, it applies to the entire 
right argument at once, rather than independently to multiple. 
cells within a right-argument frame. 


Major cells Each partitions its right argument into major cells. The ad- 
verb whose symbol has a cross bar (that із, 4 or x) produces 
a derived verbs that splits the argument array into major cells 
along the first axis. That is the standard way. 


An sdverb whose symbol lacks the cross bar (that is, / or 
N) produces a derived verb that splits the right argument into 
cells along its lass axis rather than the бги. They are what 
this manual sometimes calls contra-major celis* 


‘The way in which the derived verb uses the cells in йз argument is explained 
in what follows, 


Summary of Forms 
The argument of the adverb E or x may be eicher а verb or a noun. 


Verb argument The verb's dyadic use is understood. Although “A Dic- 
tionary of APL” permits any verb, in APL the verb must 
by a primitive and must be a scalar verb (that in, а verb 
whose argument ranks and result rank are all 0). In 
Figure 6— 1, the letter v stands for the appropriate verb 
symbol. 


Noun argument The noun must be a numeric list. This list is used to 
control what is done with the first-axis or last-axis cells 
imo which the derived verb partitions its argument. In 
Figure 6-1 , the letter я stands for the appropriate noun. 


Heeg. 


introduced first, which is why it has the simpler symbols. Receat theoretical work now 
‘considers the L def R juncti 


то be primary forma und derives the Lal, forms by ше of the rank conjunction, 
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The four forms, with their derived verbs named, and the argument rank of 
the derived verb that each produces, are summarized in Figure 6-1. (The 
rank for dyadic use of the derived verb is shown in brackets, since there 
are no dyadic uses in APL.) 


Мате of the 
derived verb 


»-reduce ш 
vacan w 
s-replicate w 


compress w 
(when я is Boolean) 


s-expand w 
Figure 6-1 : Verbs derived from the slash adverbs. 


For the corresponding forms with / rather than з and with N rather than N. 
use the names shown in the figure qualified by the phrase fast-axis, as in 
“fast-axis reduce,” “last-axis scan,” and зо on. 


Monads Scan and Reduce 
When the argument of » or X is a verb, as in 
r xX ог wy X 
the derived verb splits the array X into cells and applies the verb v as a 
dyad between each of them. 
Reduce The result of reduction is found by evaluating the verb v between 
ali the cells thus formed. 


Scan The result of а scan is built up as a series of cells by evaluating 
the verb v for the first argument cell, the first two argument cells, 
the first three argument cells, and so on. 


Effect of Order of Grouping on Scan and Reduce 


Because а scan's f. result cell is constructed from the first n cells of the 
argument, but APL's leaf-1o-root execution implies evaluating the fast verb 
first, the value of the (n+7}* cell is obtainable directly from the w. cell 
only when the verb is associative. You can see this in a simple example 
with the non-associative verb subtract. 
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Example: Suppose х is a numeric array having three axes, with lengths 4 
5 6. A scan or reduce splits x along the first axis, forming four cells, each 
of which is a S-by-6 table. Call those tables xl. Xs, Xs, and X. Then -xX 
relums a 4-by-5-by-6 result, whose four tables (each S-by-6) are computed 


respectively by: 
Xx = n 
Xı- Xa = xh 
Xi- Xi - Xs = XI - (X X, 
XI - XIX. X. = XI - (Az (Xa 7 X0) 


The left-to-right grouping for the cells produced by a scan was deliber- 
ately adopted because, in this order, the scans produced by several non- 
associative verbs produce valuable results. For instance: 


-xw Alternating sum of cells of w. 
#w Alternating product of cells of w. 


In the result of any scan, the first cell is the same as the first cell in the 
argument, and the last cell is the same as the result of reduce. Thus, the 
single cell retumed by v wis the same as the last of the cells retumed by 
эх ш. 


Where scans and reductions are defined only for scalar verbs (as is at present 
true in APL), the result of a scan applied to an array w has the same rank. 
and shape as the argument w. The result of a reduction has a rank one less 
than the rank of w. Indeed, that is why it is called "reduction": it reduces 
the rank of its argument. (When the argument of reduce already has rank 
0, the result also has rank 0.) 


Reduce When Argument Has One Cell or None 


Since the verb identified in the argument of 7 is interpreted in its dyadic 
sense, you might wonder how the verb is executed when the array argument 
has only one cell. (What is the sound of one hand clapping?)* 


By definition, when the array argument of the derived verb has only one 
cell, the result of reduction by amy verb is that cell, unchanged. (That holds 
true even when the values in the argument cell would otherwise be outside 
the verb's domain, as for example aa. 


When the array argument of the derived verb has no cells and the reduction 
is by a primitive verb with a known identity element, then the result is a сей 
whose value is that identity element. An identity element for a dyadic verb 


4 See also the discussion of identity elements for reduction in the fist pert of Chapter 5, “Verbe”. 
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is a value that causes the verb to retum a result thai is the other argument. 
unchanged. Thus, the identity element for addition is 0 because adding 0 to 
another number does not change it; the identity element for multiplication 
is 1, and so on. 

For f (maximum), the identity is that value compared to which all other 
numbers arc grealer. In principle, it is minus infinity; in practice, it is the 
smallest representable number. Similarly, for L (minimum), the identity is 
that value compared to which all other numbers are smaller. In principle, 
it is infinity; in practice, it is the largest representable number. 

For some verbs, there is a right identity but not a left. For example, anything 
divided by 1 remains unchanged, but the that is not true for 1 divided by 
anything. For some verbs, there is an identity element when the verb's 
domain is restricted. For example, as long as you stick to Boolean values, 
1 is an identity element for =, 

When reduction is applied to an empty array, APL returns whatever identity 
element is defined for the verb. The values of the identity elements are 
shown in Figure 6-2. 


None 
None 


Smallest representable number 
77.2370055773322621е75 

representable number 
7.2310055773322621e75 


x 
* 
Р 
< 
> 
> 
5 
* 


Figure 6—2 : Identity elements for scalar dyads. 
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Some Examples of Reduce 


Reductions and scans are among the simples, yet most powerful, facilities 
in APL. The average grade of each student is a course can be found from 
8. their table of quiz scores, by: 


(+/5)+71#р5 


The largest and smallest items in each row of an array are found with [/w 
and L/«, respectively. 


Questions relating to Boolean criteria are easily answered with reductions 
on Booleans: 
V/bal»1000 & Does anyone have a balance in excess of $1000? 
A/parts€catalog ^ Do we have all the parts required? 
+/graph n How many paths exist in the graph? 


Some Examples of Scan 
Scans, like reductions, аге effective tools for a variety of computations: 


One way to left justify a table of text is to count the number of leading 
blanks in each row, then lefi-rotate each row of the table by that amount, 
To do this, use and scan to locale the leading blanks, and plus reduce to 
sum them: 
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Hte4 9P'This text is not yet aligned’ 
This text 
1s not 
yet 
aligned 
ts! * 
000010000 
100100011 
111100011 
110000000 
ANEZ! * 
000000000 
100000000 
111100000 
110000000 
N 
0142 
[AIDE 
This text 
is not 
yet 
aligned 


Sum scan can be used to create a moving average function, such as might 
be used to filler out high-frequency noise, such day-to-day price fluctuations 
in a series of stocks. Consider a three-day moving average of prices, and 
the sum scan of prices: 


prices 
8318478 

HSe+\ prices 
8 11 12 20 24 31 39 


If the first two elements of 5 are ignored (three days, remember?), the third 
item of the sum scan corresponds to the sum for the first three days. The 
fourth item is the sum of the first four items, the fifth is the sum of the first 
five, and so on. To get the moving sum, all we have to do is to subtract 
appropriate numbers from 5: 


o The sum of the first zero clements of prices from the third 
item. 


8 The sum of the first one element of prices from the fourth 
item. 
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11 The sum of the first two elements of prices from the fifth 
item. 


12 The sum of the first three elements of prices from the sixth 
item, 


20 And so on. 


Noting that these numbers, aside from the first zero, are merely elements 
of the sum scan, we can complete the moving sum with the following 


expression: 
(28-0, 348 

12 12 13 19 19 

The complete expression for the a-period moving average of a list w is: 
(C- 0r)-0, C70) ref) +a 


The addition of two rank conjunctions allows the verb to be used on arrays 
of higher rank: 


(((а-1)+%1 r)-0,(-8)491 ret\w) +a 


Scans on Boolean arguments are also powerful. AN computes the running 
parity of a Boolean list. This can be used for such purposes as locating 
quotes in text <\ will isolate the first 1 in each row of a Boolean array. 


The Derived Verbs Replicate and Expand 


When the argument of E or x is a noun, the derived verb splits its argument 
into cells and then copies (or replicates) the argument cells, or expands the 
argument array by inserting new cells. 


m corm/ w — Makes x copies of the cells of w. 
7 copies major (first-axis) cells. 
/ copies contra-major (last-axis) cells. 
RX wor «N о Inserts "fill" cells between existing cells of w. 
x inserts major (first-axis) cells. 
\ inserts contra-major (last-axis) cells. 


Replicate 


The adverb’s argument я indicates the number of times to copy each major 
cell of the derived verb's argument, Each item in m must be a non-negative 
integer, and the length of m must match the length of the appropriate axis 
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of ө. Allematively, where a is an item, it is applied to cach of the cells in 
. 


The number of cells in the result is the sum of the values in и (or ж times 
the number of cells, when a is an item). The result consists of replications 
of the cells of the right argument. For example: 


кхе ¥7 'First! > 'Second' э 'Third' 
First 
Second 
Third 


3 0 24x 
First 
First 
First 
Third 
Third 


Compress 


A commonly used subset of replicate occurs when the values in the list a 
are Boolean (that is, are all cither 0 or 1). In such a case, a cell from the 
derived verb's argument is either retained in the result (where я has а 1) 
or discarded (where # has a 0), In that case, the derived verb is called 
compress, since the result differs from the argument only in having certain. 
cells removed. This often occurs in an expression in the form: 


(Proposition onw) и w 


Here Proposition on stands for any APL expression thal takes w as an 
argument and retums a Boolean result with a 0 or 1 for cach major cell 
in & for example, (Oe w)/w (“accept any cell that contains a zero"), 
The result of this compression retains from w those major cells for which 
the proposition is true (represented by 1) and omits those for which the 
proposition is false (represented by 0). 

For example, the set of odd numbers could be extracted from а list of 
numbers using compress in this way: 
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L 

19222 55 987 88 100 .5 33333 
(12177 

1 9 55 987 33333 


Expand: Introducing "Fill" Cells 


The noun argument to X or N is required to be a Boolean list in which the 
number of occurrences of à 1 agrees with the number of cells along the 
axis of the array you are about to expand. Occurrences of а 0 produce fill 


items appropriate to the type of the array you are expanding 
0 for a numeric array 
v * fora character array 
<10 for a boxed array. 


For example, using the array X defined above to illustrate replicate: 


, 10 0% NX 
*First 
* 
Second 
* 
*Third 


Derived Verbs Modified by Axis Bracket Notation 


All the derived verbs produced by и / x or N work by partitioning the 
derived verb's right argument into cells. As mentioned, the derived verbs 
produced by и and x partition along the first axis, while those produced 
by / and \ partition along the last axis. You can override the axis along 
which partitioning takes place by modifying the derived verb with the axis 
adverbs For example, the expressions 


#1] w afi) w 
»/l1) w 271) v 
4) w тх) w 
* w X12 ш 


1 Fil itema те described in detail in Chapter 5, " Verba" in the sections on “fll elements” and "over-take and padding.” 
T Коо sia bracket nomion does cot adhero o dhe турах or semantics of, adverbo, ia ats ia cioe to hat of 
. ТА Dictionary of APL? лаз the чы of beretat Р 
implementacions må mentions it only se a “dialectical variant.” However, 
кошл Le APL ced a каша m APE 
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ail mean that the derived verb partitions the array w along its Ё* axis rather 
than along the first or last, The value of i used by the bracket axis adverb 
is sensitive to the value of Dio. 


Conjunctions . б = 

For every conjunction, four cases are possible, based on the name-class of 
the arguments: 

both verbs 

* a noun and a verb 

e a verb and a noun 

* both nouns. 
At least in theory, each of these cases may produce an ambivalent derived 
verb (which may be used either monadically or dyadically). In practice, 
some of the cases are not implemented or defined. Figure 6—3 summarizes 
the available cases. 


Argument | Valence 


Verb, verb 


Figure 6-3 : Conjunctions. 


Grouping in the Discussion of Conjunctions 
In the sections that follow, the discussion of conjunctions is grouped not 
by symbol but by related use. The sections are: 


Composition: 8 


Ы with arguments v v 

Rank: * with arguments v я 

Cut: * with arguments # v 
Product: . with arguments v — . 
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Conjunctions 8 " with Verb Arguments 


"When one of the conjunctions З, +, or is used between a pair of verbs, 
it forms a new verb that is a sort of composition of the two verbs. In what 
follows: 

J denotes the verb that is the conjunction's left argument 

g denotes the verb that is the conjunction's right argument. 


Each of the three conjunctions 8, 2, and may take two verbs as its ar- 
guments: one verb which it uses monadically, and another which it uses 
ambivalently. Each of the three conjunctions produces an ambivalent de- 
rived verb. They differ in which of the argument verbs is monadic and 
which ambivalent, as follows: 


fög Upon. The right argument g is the ambivalent one. It acts on 
corresponding cella of the derived verb's array arguments a and 
w (or just on cells of w when a does not exist). 


fg On, The lefl argument f is the ambivalent опе. It acts on the 
corresponding cells produced by applying ¢ to cells of а and to 
cells of w (or just to cells of w when a does not exist). 

Under. Like f *g. However, to each of the cells produced as in 
Fug. it then applies g', the inverse of д. 


Under Requires a Known Inverse 
Because f automatically applies not only the monadic verb g but also its 
inverse, the choice of g in compositions such as f is limited to verbs for 
which APL already knows the inverse. Therefore, ¢ must be taken from 
the following list of primitive monads (inverses shown below). 
Mond: & ® > < - + в B ~ к + 
Inverse: ө x < > - + 8 HB ~ - + 
Several of these verbs are self-inverse. The verb + is self-inverse because, 
used monadically, il is an identity function (giving back as result the same 
value it received as argument). 
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Derived Verbs Produced by Composition 
In Figure 6-4: 


LA denotes the left array argument of the derived verb 
& denotes a cell within LA 
RA denotes the right array argument of the derived verb 
w denotes a cell within RA. 


LA Јр RA :1 2 (ga) уро 
Ferm .I el 1 7 
Under 
LA f"g ВА 7. 1 f: 2 e go feo 
— | 


Figure 6-4 : Composition templates. 


Default Rank of the Derived Verb 


А conjunction can accept as а right argument only a primitive verb having 
a known default argument rank. Thus, a verb whose default argument rank 
is shown by a * (in Figure 6-1 or in the descriptions of the various verbs 
in Chapter 5, “Verbs” is ineligible. 


In all cases, the compositions are considered close; that is, they are applied 
independently to each cell of their array argument (when they are used 
monadically) or to each of the pairs of corresponding cells (when they are 
used dyadically). 


The verb derived from a composition conjunction divides its argument(s) 
into cells in the same way as would g, the verb to the conjunction’s right. 
In particular, the rank of a verb derived from fög is the same аз the rank 
of g. and the rank of verbs derived from either F 2 or fg is the same as 
the monadic rank of g. 
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Figure 6-5 : Three forms of composition. 
The diagram in Figure 6-5 presents a graphic summary of the way the 
argument verbs of the three conjunctions are applied to cells of the argument 
array when the derived verb is used dyadically. 
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The Rank Conjunction vn 
When the left argument of Y is a verb and the right argument is а noun, 
the noun specifies the verb's argument rank. For example, the expression 
а «502€ 
indicates that the verb + is to be applied to rank-O cells of а and rank-2 
cells of w. That is, each item in a is to be added to the corresponding table 


in w. (The frame-shapes have to match. That is, the arrangement of items 
in a has to match the arrangement of tables in w.) 


Similarly, the expression 
* 
encloses each list (that is, each rank-1 cell) of a. 


The noun argument of & must be an item or а list, and it may have one, two 
or three integers. It takes three items to describe the verb's monadic rank 
and the dyadic ranks of its lefl and right arguments. When the argument 
я has fewer than three items, the values for all three are implied by the 
expression 
фзрфп 

Calling the items within the noun a, b, and c respectively (when the noun 
has one, two, or three items), they specify the argument ranks as shown in 


Figure 6-6. 
Monadic | Dyadic Dyadic 
А rank lef rank | right rank 
abc a b c 
ab b a b 
a a a 


Figure 6-6: Short forms of rank specification in c. 
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Argument Rank vs. Complementary Rank 
When an item in the right argument of * is positive, it specifies the number 
of trailing axes in an argument cell. Any remaining axes are frame axes. 
When an item in the right argument of i is negative, its magnitude specifies 
the number of leading axes in the argument frame. Any remaining axes 
are cell axes. It is thus the complement of the way rank is specified by а 
non-negative right argument. 
For each of the cells within the frame thus defined, the verb is evaluated 
with its "ordinary rank": as it would be evaluated if not modified by the 
rank conjunction. For example, 


<71 0ш 


specifies that the frame rank is 1, and thus < (box) is applied independently 
to each of the major cells of w. 


Within Cells, the “Ordinary” Rank Applies 


The rank conjunction controls the initial partitioning of the arguments into 
frame and cells. To each of those cells, the verb's "ordinary" definition 
applies — the definition unmodified by the rank conjunction. 


"When the cells thus defined have a rank greater than the rank for which 
the verb is defined, then the verb is applied to each cell with its default. 
rank ~ provided default rank is defined for that verb. For example, to add 
the nine-clement list a to each of the rows of the nine-column table w, you 
write: 
а +1 w 

That pairs the list a with the list w[1; J. then with the list w[2 ; }, and so 
on. For the first result cell, the interpreter evaluates: 


а + o(1;1 


The verb + had default argument-rank 0. The verb + is then applied to 
the arguments a and «[1;] with rank 0. That causes a new level of 
partitioning between frame and cell. In this example, each argument cell is 
partitioned into a nine-elemcnt frame consisting of rank-0 cells. а(1) is 
added to (w£131)[1J, a(2) is added to (90152) (21, and so on. 


Default Rank Not Defined for Some Verbs 


А verb’s default rank is the argument rank it assumes when the rank is 
not explicitly stated with the rank conjunction. For example, monadic use 
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of @ has default rank 2. If x is а rank-3 апау and you write Ex. it is 
automatically assumed that you mean to apply E to cach 2-cell of x. 


For some verbs, no default rank has yet been defined. For example, monad 
\ is defined when w is an item (or a one-item list), If x is a rank-3 array 
and you write 1x, it is not assumed that x is to be treated as a collection 
of rank-0 cells and 1 evaluated for cach. Instead, the expression is rejected 


as rank error. 


When you use a verb for which default rank has not been defined, the rank 
conjunction can be used only to assign a rank acceptable in the ordinary 
case, For example, the expression 170 x is valid because 1 works on a 
rank-O argument. And the expression 1%1 x works when the last axis of 
X has length 1 (because 1 works on a onc-item list, even though it cannot 
handle a list of any other length). 

“That is the point of the phrase “ordinary rank" in the preceding section. 
"When you use the rank conjunction to partition the argument into cells, the 
interpreter applies to each cell the ordinary definition of the verb. When 
the verb has a default rank, the default rank is used; this may then lead to à 
further partitioning within each argument cell, But where there is no default 
rank, the “ordinary rank” — the rank with which the verb is ordinarily used 
— is the only one permissible. In these cases, you have to supply arguments 
that meet the verb's requirements for rank and shape. 


Examples of Rank 


Before the rank conjunction was available, adding a list to cach row of a 
table might have performed with an expression such as: 


tablet(Ptable)Plist 
With rank, it is you merely specify the use of rank-1 cells: 
liste*1 table 


The use of rank allows terser expression as well as offering the potential 
for faster execution in less space. Adding a list to each column of a table 
is a bit subtler, but is done as follows: 


list+80 1 table 


This takes advantage of scalar extension in +, by setting up scalar cella 
from the list, and list cells from the table. Effectively, each element of the 
list is added to the corresponding row of the table. 
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The Cut Conjunction пу 


When the left argument of ¥ is a noun (other than 0) and the right argument 
is a verb, the derived verb cuts the argument amay w into segments by 
splitting it at points along its first axis. A O- en selects arbitrary cells from 
the argument array. Cut then applies the verb on the right to each of the 
segments thus obtained. 


The left argument s of ? is an integer specifying the type of cut, я must 
be an item; frame considerations do not apply to il. The value of т must 
be one of 2. 1, 0, 1 or 2. 


When the derived verb is used dyadically, the derived verb’s left argument 
а specifies the positions in w at which is to be cut. To each of the cells 
produced by a cut, the verb > is applied monadically. 


Between them, the derived verb and the conjunction have four arguments; 
they are summarized in Figure 6-7. 


n v y @ 
Туре Verb Array argument 
of cut (monad) | of the derived verb 


Offset and length 0 
(required) (to be cut based 
оп the value of 
Boolean mask the left argument) 
(optional) 


Figure 6-7: Arguments of the cut conjunction and of its derived verb. 


Types of Cuts 

For every type of cut, the derived verb has unlimited right argument rank: 

it applies to the whole array, not independently to cells within the array. 

When the derived verb is used dyadically, its left argument rank is either 1 

or 2, depending on the type of cut. 

The type of cut is controlled by the value of # as follows: 

«=0 Баф cell is selected by an integer table specifying the offset and 
length along each axis. 

n#0 Cells are selected by a Boolean list delimiting segments along the 
first axis of ш, 
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Cells Selected by Table 


When я is 0, the derived verb has left argument rank 2. Each table in 
в describes the position and shape of a cell passed to the verb v, The 
description is a table having lwo rows and a column for each axis of ш. 


Within each a-cell, rows have significance as follows: 


Row 1: Offset along w’s various axes after which a block is to start, For 
example, an offset of 2 means that you skip the first two positions 
before starting the block. A negative offset means “all but.” For 
example, an offset of 2 means you skip all but the last two 
positions before starting a block. An offset of 0 starts at the 
beginning of an axis; an offset equal to the length of the axis 
means “start at the end”; it is valid only when the length you ask 
for h 0. The magnitude of the offset may not exceed the length 
of the corresponding axis of w. 

Row 2: Length along each axis for the block you are selecting. The 
magnitude of the value you write here governs the length of the 
block. The offset plus the magnitude must indicate positions that 
actually exist along the corresponding axis of w. 

The sign of a value in row 2 affects neither the size of the block you 
select пог the positions from c that go into it. The sign controls the 
order in which the selected positions appear in the block. A negative 
value selects the same positions, but places them in the segment that 
is passed to the verb v in reverse order. 


For example, here is an а-сей that describes a segment to be cut from a 
rank-3 array w. Since w has three axes, an а-се must have three columns. 
Thus, 


indicates that from the right argument a cell is to be extracted as follows: 
Axis 1: Offset: Start four positions after the beginning of this axis. 
Length: From there, continue for two positions; 
Axis 2: Offset: Skip all but the last three positions of this axis. 


Length: From there, run for one position in the standard direction 
(thal is, towards the end of the axis). 

Axis 3: Offset: Start five positions after the beginning of this axis. 
Length: From there, run for three positions in the usual direction 
(that is, towards the end of the axis). However, because the length 
is negative, place the selected positions in reverse order in the cell 
passed to verb v. 
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The 0-cut requires a considerably more elaborate left argument than the 
1-cul or 2-cut, with a distinct a. cell for cach cell passed to v. However, 
the 0-cut permits you to specify the lengths а segment has on all its axes, 
not just the first, It also permits overlapping segments, or empty segments. 


The following example shows how multiple pieces may be selected in 
parallel from a table: 


breS 59125 
123 45 
6 7 8 910 
1112131415 
16 17 18 19 20 
21 22 23 24 25 


reed 2 2000 2 3.0 0 2 73,1 2 3 2,2 2 3 1 


Т1 шы 171 
11231 18761 [8 91 1241 
16 7 8} |3 2 11 113 141 1191 
اا اسا‎ 118 19| 114! 
l Ды} 


Cells Selected by Boolean Partition 


When и is other than 0, the derived verb has a left argument of rank 1. 
Each item 1 in the a-cell marks the start (or end) of a cell passed to the 
verb v. Each Boolean list therefore generates as many cells as it contains 
1s. To permit the result to be constructed, each a-cell must contain the 
same number of 1s. The box verb («) is often used to make this possible. 


Each cell has the same rank as w and the same length as w along all its 
axes except the first. Along the frst axis, a cell passed to v has a length 
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that depends on the distance between consecutive 1s in the a- cell. The 
positions selected for each cell are controlled by the value of я as follows: 


nel 1 Each 1 in an a-cell marks the start of а segment. The first 
segment starts at the first 1; positions before it are not repre- 
sented in the result. 

тє2 2 Esch 1 in an a- cell marks the end of a segment. The last 
segment ends at the last 1; positions after it are not represented 
in the result. 

m positive The position corresponding to each 1 in an a-cell is included 
in the result cell. 

m negative The position corresponding to each 1 in an a-cell is not in- 
cluded in the result cell. 

To make the selections produced by cut readily visible, use « as the right 

argument, putting cach cell into а box, and make the boundaries of the boxes 

explicit in the display by setting by selling Ops to 1 1 73 73. Then 

а n*« w shows how the . cut divides the array argument. For example: 


wet Worlds on worlds* 
(wet °) 17% 4 Opse-1 13 3 


i Worlds|| onl| worldsl 
1L Hl i 


(Quet'Wow!) "19«9 
b AIT 
Iwi lorids| | onl wl |orlds| 
1-1! ИНЕ [ 


APL programmers make extensive use of Booleans, particularly in the par- 
titioning of data. One way to easily find the lengths of the partitions іп a 
Boolean partition vector ia to let cut do the work for you: 


1901000110010 


vere 


+Table+ 5 4Р120 
1234 
5.6 7 в 
9 10 11 12 
13 14 15 16 
17 18 19 20 
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Table 4 Opse-1 1 3 3 
[ 

15 6 7 81117 18 19 20] 

19 10 11 121— —l 

1 ] 


Monadic Use of 1- and 2-Cuts 


‘The 1-cut and 2-cut, but not the 0-с, can be used monadically, When 
you use the derived verb monadically, the cuts are made by treating the 
first (or last) of the major cells of w as the delimiter. The result is what 
you would get if you had included « as the Boolean list computed as: 


Le . (18) эйеп l 


оеш SS 1 e x,«972 (1% when 2=1я 


That is, the partition list а is formed by comparing the major cells of w 
with the first major cell or the last major cell of w. 


For example, the following encloses each word (delimited by a blank) in 
the character string w 


7186 0 tw 
while the following arranges each of the equal length character strings 
between slashes into a table 


15 7 


Shape of the Result Produced by Cut 


The result produced by dyadic use of a verb derived from cut has the frame- 
shape required by the values in а, followed (when nE) by the number of 
partitions, followed by the common cell-thape resulting when the verb v is 
applied to the cut cells. Because APL currently requires that result cells 
agree in rank and shape, the box adverb is often used to force all result 
cells to be items. 


Dot Conjunctions 


‘The following table summarizes the cases of the dot conjunction, and the 
names associated with them. Outer product, Inner product and Alternant 
are discussed separately in what follows. 
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Monadic use 
Argument || of the derived verb 


Dyadic use 
of the derived verb 


Outer Product 


Figure 6—8: Verbs derived from the dot conjunction. 


Tie and Outer Product 


The APL outer product is a particular case of what "A Dictionary of APL” 
calls tie.’ The outer product relaxes the usual rules regarding agreement 
of frames, and instead pairs each O. cell of а in tum with each of the O cell 
of w. The result contains all possible pairings of an a-cell with an «celi. 
The resulting frame has shape (Pa) , (Pw). 


The outer product is written: 
ago 


The argument g must be a primitive scalar verb (that is, one that is defined 
for rank-O arguments and that retums a rank-O result). 


‘The result is obtained by pairing each element of а with each element of 
w. One might specify the result r by the following formula: 


shape + (pa), 
r + ((pw)ps1 D а) g shapepw 


Notice that when either a or w is an item, an outer product gives the same 
result as the verb without the dot conjunction. 


When the arguments are lists, the result is a table. For example, if a is the 
first three integers and w the first five, then a» .xw forms a multiplication 
table: 


he corresponding woli), the ne conjunction allows you to tpecify how many ates must agree. That leaves all the 
be fied. The result’s frame-shape is : 

race shape of ы. When the number of tied axes is Û, you have the our product. Аза 

mbuime for & 0 f ы, “А Dictionary of APL” permits a e.g w, which is the form provided in APL. 
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d . o 489123 40912345 
E &c5 
2 4 6 810 
3 6 


Below appears a division table formed from the same lists « and . 


а о,+ w 

1 0.5 0,3333333333 0.25 0.2 
2 1 0.6666666667 0.5 0.4 
3 1.5 1 0.75 0.6 


The expression a+ . 2 produces a logical map showing where an element 
of а is not less than an element of ш: 


а 3 w 
10000 
01000 
00100 

a 4 0 
01111 
00111 
00011 


Similarly, ж . w produces а table of residues or remainders: 


Anda . w gives a table of the differences between elements of a and 


those of w: 

2 — 
071727374 
1. 0 13 
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If alf is a list containing the letters of the alphabet, and text is a list 
representing the text of a document, then al fe text gives you an inci- 
dence map showing where the letters of the alphabet are in the text, while 
4/alfe.-text gives you the number of occurrences in text of cach 
letter in alf. 


inner Product 


The expression a+, xo is equivalent to the dot, inner, or matrix product 
аз defined in mathematics for vectors (cart) and matrices (where the 
element in row 1 and column J of a+, хш is the dot product of row 1 of 
@ and column J of 4), For example: 


1237. 345 
26 


a*2 3P16 4 be3 49112 4 Olorl 
а +.х b 

38 44 50 56 

83 98 113 128 


a+x123 
14 32 
The inner product can be used not just with + and x (the dot product of 
matrix algebra) but with any of the primitive verbs that take item arguments 
and retum item results. For example: 


6 6 6 
12 13 14 15 


Result Shape of inner Product 


The result produced by an inner product resembles the shape produced by 
outer product, except that the two inner axes — the last axis of a and the 
first axis of ш ina f.g ш — disappear in the result. Hence, the shape of 
the result ofa f.g wis ( 14P9) , 1560 


Extending One Argument to Match the Other's Length 


їп general, the inner axes (that is, the last axis of a and the бга axis of «) 
must match in length. However, APL also accepts two other cases: 
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. When the inner axis of one argument has length 1, but the inner axis 
of the other argument has some other length. APL treats the length-1 
axis as though it were extended to match the length of the other one, 
replicating in each position whatever value is in the first position. 

. Similarly, when one argument is an item, APL treats it as if it were 
а list of the same length as the inner axis of the other argument, 
replicating at cach element the value of the item. 


Neither of these extensions affects the shape of the result. 


Inner Product and Matrix Product 


When a and w are matrices, the inner product a+. xu is the same as the 
ordinary matrix product of matrix algebra. Note that matrix product has an 
inverse, since, where а and ш are non-singular square matrices: 

w e» (at, xu) Br 
See the discussion of matrix division and matrix inverse in the discussion 
ol Ifl in Chapter 5, “Verbs”. 
Evaluation of polynomials. The ordinary matrix product a+, xw can eval- 
uate polynomials in w, Suppose coeff is a table (of any rank or shape) 
containing the coefficients of the polynomials to be evaluated. The finit 
axis of coeff contains the terms, starting with the constant term, the first 
degree, second degree, and зо on, up to the desired degree. Let powers 
be an array in which each member of « is raised to each of the powers, 
from zero up lo whatever degree is implied by the length of the first axis 
of coeff. That can be calculated by: 


powersea . (YltPcoeff)-Dio 


Then all of the polynomials for each of the sets of coefficients in coeff 
can be calculated by: 


powers +.х coeff 


Product of powers. One way to represent an integer is by ils prime factor- 
ization. That is, you can represent an integer by a list indicating to what 
power cach of its possible prime factors must be raised. The integer is then 
the product over each of those powers, For all the primes in order out to 
the largest one needed, suppose factors is an array containing the power 
10 which each must be raised. Then the values represented by such a set 
of prime factors are found by 


primes x.* factors 


where primes is а list of the values of as many primes as are needed to 
match the length of the бга axis of factors. 
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Locating characters from one table within another. Inner products con- 
structed from logical verbs on character data are frequently useful in han- 
dling textual data. Suppose sample is a character matrix in which each 
row contains characters spelling a word, phrase, or name. Suppose ref- 
erence is а similar table of recognized words or phrases. You need to 
know where within reference each row of sample is to be found. A 
map showing where each row of sample is entirely equal to a row of 
reference is obtained by: 


reference . Nsample 


Altematively, rather than identifying those rows of reference which are 
entirely equal, you might wish to eliminate those that are in any way dif- 
ferent, by an expression such as: 


reference v. * Ssample 


If you want 10 convert the resulting Boolean map so as to identify the 
number of the row on which each match was found, that might involve 
another inner product. Suppose {ota is a list of consecutive inlegers, with 
as many members as there are rows in reference, perhaps formed by the 
expression: 

lota- 11 reference 
The location of the match for cach row of sample is found by: 

iota +.х reference ^.z Ssample 


The preceding formula assumes that reference does not contain duplicate. 
entries. But if it did, and you wanted the highest entry, you could find it 
as: 

iota [.x reference. sample 


If you are interested in the extent of agreement (rather than simply the 
Boolean decision whether or not there is perfect agreement), you might get 
thal by: 


reference +.= Qsample 


Permutation and partition matrices, You can permute or partition the 
members of onc array by making one of the arguments of an inner product 
a Boolean array. The Boolean matrix b might contain a column for each 
of the desired partitions. In the expression b+. хш, a 1 in b indicates that 
а row of w is included in a partition, and а 0 indicates that it is not. 


When there are as many partitions as there are rows, and each row and 
column contains exacily one 1, the matrix is a permutation matrix. It 
specifies an order in which the rows of are represented in the result of 
bt. xw, 
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A Boolean array acts as a partitioning device when the verb g, applied to 
0 in the Boolean array and any value in the other array, yields the identity 
element for verb f. For example, with the +. x inner product, 0x any value 
in the other array yields 0, which is the identity element for +. That is, 
elements marked 0 in the Boolean array have no effect on the sums. 


Similarly, in an inner product such as ax. xb, raising an clement of a lo 
the power 0 yields 1, which is the identity element for x. For other ways 
of partitioning, see also the section on the cut conjunction. 


‘Analysis of connectivity, You can evaluate the connectivity of а Boolean 
graph with inner products. If each row of a matrix c indicates a node of а 
network, and each column a connection to that node indicated by а 1, then 
the existence of a direct connection is found by 


с У.А Bc 
and the number of connections by 

C *. A Rc 
Applications in circuit analysis will be familiar to electrical engineers, but 
analogous calculations occur in other fields. For instance, the connectivity 
of an urban transit system might be documented by tabling the stops as 


rows of a matrix and the lines that serve them by columns. If such an array 
is called map, the connectivity of the system is found by: 


с+(®тар) v. A map 


The result c is square matrix showing where опе line intersects another. 
А map showing which line is connected to another is found by 


с v. A Nc 
and showing which line can be reached in a two-step joumey by 

€ v. A Rc v. A Rc 
and so on. Continuing this process until the result does not change produces 
the transitive closure of the graph. In the case of the transit system above, 
it would show all stops you could get to from any other stop, and would 
tell you if indeed “You can't get there from bere." 
Other uses of v. ^ include the computation of cross-references, calling trees, 
and gencalogy trees. 
Inner product involving reduction by a non-associative verb. The dot 
conjunction’s left argument f reduces each of the outer products generated 


with the right argument g. The alternating sum or product may serve there as 
it does in reductions. For example, the MacLaurin series for approximation 
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of the sine is shown conventionally as the altemating sum of ratios of 
successive odd powers: 


P CLER x" oc a? г 
ETE 3i 57 7 31 


In APL, this simplifies to the . . inner product, as follows: 
sin а = (o- od -.* todde 142xX1k 4 0101 


Monadic Use: The Alternant 


The expressions -. xc) and +. xo are, for square matrix arguments w, the 
determinant and the permanent of mathematics." 


The generalization to arguments other than +, -, and x is based on con- 
struing the determinant as an alternating sum (-») over products over the 
diagonals of matrices obtained by permuting the major cells of ш. 


Applied to а matrix of coefficients of a set of linear equations, the determi- 
nant identifies the character of the solutions; applied to the matrix of partial 
derivatives of a vector function on vector arguments it yields the volume 
transformation effected by the function; and applied to the matrix s,1 it 
yields 11s times the signed volume of the simplex of ne1tPs vertices 
in (n~1)-space. 


‘The determinant is generated by the expression 
-xM 


where Mis a rank-2 array, usually square, but possibly with more rows than 
columns. Only the “top-left square” portion of an array with more columns 
than rows is considered; that is, M is truncated to be (ИРМ) tM. 

The general case f.g M із defined analogously as reduction by f over a 


sel of Lne1tPM "products" produced by reduction by g over In distinct 
sets of n elements chosen one from each row and column of M- 


‘The ordinary determinant . N on a square matrix may be used as a test 
for invertibility before applying E. 

The determinant of a square matrix M may be defined as the altemating 
sum (-/) of the 1n-1 P products over n elements chosen (in each of the 
1n possible ways) one from each row and column. Analogous calculations 
in which other function pairs arc substituted for - and x lead to other 


P discussion thet follows in condensed from “А Dictionary of APL,” and from К.В. Iverson, Determinans-Like Functions 
Produced by the Dot Operator, SKIN 42, Toronto: IP. Sharp Associates, 1982. 
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useful functions; examples include the pairs |. ГМ, ^. VM, and +. хм, the 
last (called the permanent) being useful in combinatorics.? 


Suppose M is a magic square of order 3, then: 


360 


900 


Non-Square Arguments 


‘The extension of the altemant to non-square arguments allows the use of the 
determinant . x on an n+1-by-n argument to compute the signed volume 
of the simplex it represents in n-space. 

When M has more rows than columns, x/se( 1 4PM) t11 tPM distinct sets 


of 110 elements can be selected without repetition of either column or 
row, and these are arranged in lexical order in an array of shape s. For 


example: 
юм+?4 209 

64 

5.5 

43 

14 
E 

21 


For a wide matrix M, the result of f .g Mis equivalent to f.g (L\PM) tM. 


The case of -. x applied to an nt1-by-n matrix is of special interest because 
it is equivalent to —. xA, 1, and can therefore be used to compute the volume 


V Son HJ. Ryser, Combinatorial Mathematics, Caras Mathematical Number 14, Mathematical Association of 
‘America, distributed by Jobn Wiley and Sons, Inc. Providence, RL, 1963. 
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of the simplex defined by M without explicit catenation of а final column 
of 18. 


If a, b, and c are two- element vectors, then 
-.xMe3 2Pa,b,c 


yields twice the signed area of the triangle with vertices a, b, and с. The 
sign of the result depends on the order of the vertices, positive when they 
are in counterclockwise order and negative when they are in clockwise 
order. For example, if: 


aei 1 4 bel 04 coO 1 


.* 2ра,Ь,с 


. * 2Pb, a. c 
1 


The signed result of —. x is significan in higher dimensions as well. If a, 
B c, and d are points in threc-space (in а dextral coordinate system), then 


. * 4 3Pa,b,c.d 


gives (13) times the signed volume of the tetrahedron, the results being 
zero if the points are coplanar, and positive if the points b, с, and d are in 
counterclockwise order when viewed from a. For example: 


a-1 11 D 0 Û 4 c*0 N 021 


=.x4 Ia, b. o, d 
2 

-.х4 302, c, b. d 
E 
The use of functions other than - and х can be illustrated in the context of 
the so-called assignment problem. One of n persons (or machines) is to be 
assigned to each one of n tasks in some optimal way, the cost associated 
with assigning person i to task J being given by clement M11; J] of the 
‘square matrix М. 


То minimize the sum of the costs in the assignment, the optimum value is 
given by . , since the summation +/ is applied to cach of the 11 t 
possible assignments, and the minimum 17 is applied over them. 

Other useful function pairs in assignment type problems include Г.+М, 
L. ux T.xM, L.FM and T. Lx 


February 1993 Adverba and Conjunctions 6-35 


SHARP APL Reference Manual 


A square Boolean matrix B is said to be a Latin square if it contains exactly 
1*PB ones, with one in each row and one in each column; one Boolean 
matrix C is said to cover another, D, if A/,C2D. The expression v. Ac 
yields 1 if C covers a Latin square, and the expression +, AC tells how 
many distinct Latin squares are covered by С. 
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This chapter describes the various mechanisms by which уой enter the 
definition of a user-defined verb or edit the definition once it has been 
entered. To write your definition appropriately, and to edit it when it runs 
into trouble, you will also need to be aware of the way a definition is 
used, how names are localized, what happens when an error or interrupt 
is encountered, and how such events can be handled automatically. These 
topics are covered in Chapter 8, “Control of Execution” and Chapter 9, 
“Event Handling”; you may need to consult those chapters in order to 
elucidate some of the points raised in this one. 


Mechanisms for Defining and Editing Verbs 


‘APL has three main syntactic classes: nouns and pronouns; verbs; adverbs 
and conjunctions. Members of these classes are formed and named in 
different ways. 

. А noun is assigned a name by the copula, denoted by the left-pointing 
arrow +. Sec Chapter 4, “Naming Nouns and Pronouns". 

. An adverb or conjunction exists only as а primitive and may not 
be given а name. Currenily, there is no mechanism for creating user- 
defined adverbs o conjunctions. 

. A user-defined verb is produced by either of two routes: 

« The definition editor. Because you invoke the edilor by entering 
the aymbol v. it is called the v. editor or del-editor. 

* The system verbs Dfx and Dfd Each of these takes as argument 
an array of characters that represent the definition of the verb to 
be created. You can edit an existing verb by capturing its present 
definition with the verb Dcr or 1 or 2 Uf d. editing the resulting 
array, and then using Ufx or 3 Dfd to create a new definition 
that replaces the old. 

In addition to these ways of creating а new definition, a previously 
defined pronound or verb may be materialized in the workspace by: 


* Copying it from a saved workspace by means of the command 
)copy ог )pcopy, described in Chapter 12, “System Com- 
mands”. The copied verb creates or replaces the global referent 


V Bxecoting an adverb oc conjunction also produces a verb. However, the derived verb thus produced cannot currently be 
‘signed a name and thus exista only in pasting, during the execution of а sentence that cootaias sn adverb. 
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of the name. The ) copy or )pcopy commends will not replace 
a verb that appears anywhere on the stale indicator, and hence 
cannot be used to edit a verb that is in use. 

* Defining it from within a package by means of the system verbs 
Opdef or Орраеѓ, described in Chapter 11, “System Nouns and 
Verbs". The verb thus defined creates or replaces the local referent 
of the name, Opdef and Oppdef will not materialize an object 
while an object of the same name is visible anywhere on the stale 
indicator, and hence cannot be used to edit a verb that is in use. 


v-Editor 


System verbs tx or afd 


Invocation 


Interactive, You can invoke the 
editor only while your session 
is in immediate execution mode. 


АРІ. primitive, Either system 
verb may be included in any 
APL sentence being executed, 


Name Local- 
ization 


Global. The V-editor always 
creates or edits a verb having 
a global name and ignores any 
local use the name may have. 


Local, Either Ofx or 3 Ofd 
creates a verb whose name is at 
the visible (that is, most local) 
level. When the proposed name 
has not been localized, the most 
local level is the same as the. 
global level; in that case, the 
V-editor and the verbs Ofx and 
Der affect the same object. 


Editing 
During 
Suspension 


Suspended verbs. You can use 
the V-editor to edit a verb whose 
execution is suspended — that 
is, its name appears in the state 
indicator with an asterisk be- 
it. You cannot use the V- 
itor when the verb is pendent 
— that is, when its name appears 
anywhere in the state indicator 
without an asterisk. 


Any verbs, Either Dfx or 3 
Ofd can redefine any verb pro- 
vided the verb is visible. (How- 
ever, it is possible to make cer- 
tain changes that will prevent 
resumption of work on verbs 
thal are pendent; see “Damage 
to a Pendent Verb,” below.) 


Figure 7-1 : Comparison of V-editor and tx or ru 
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Representation of a User-Defined Verb 


The standard form for display of а user-defined verb, used by the V-editor 
and retumed by the system verb 1 £d, marks a definition by the symbol V 
at the beginning and end. Each line of the definition is assigned a number, 
shown at the beginning of each line in square brackets? For example, 
here is the standard display of а definition for а user-defined verb called 
growthrate: 


V z«time growthrate ratet rt 
(1) re0.0ixratet12 
[2]  *(2-Unc 'time!')/dyad 
[3] толад: сіте+1 
[4] dyad:tetimex12 
[5] 2-(1TThe. rf 
¥ 


Each definition consists of a header (the top line) and a body (Ihe rest). 


Header The top line names the verb and illustratcs its syntax. In the 
display, the lop line has по line number, during editing, you refer 
to it as line [01. By convention, the final ¥ appears on a line of 
ils own. 


Body The header is followed by a sequence of numbered lines called 
the body. The body shows the APL sentences the system should 
execute when the function is invoked. The APL system supplies 
the line numbers itself; it numbers the lines with consecutive 
integers starting at [1]. 


Canonical Form 


The canonical representation of a definition lacks the bracketed line num- 
bers and the opening and closing V, but is otherwise the same. It is displayed 
изей: 


z*time growthrate ratejr;t 
re0.01xrate*12 

*(2-Unc 'time!')/dyad 
monaditimeel 

dyad: сесітех12 

2-( 1K) Kt 


The canonical form is returned (ав a table) by the system verb Ocz or by 
2 Ufa (sce Chapter 11, “System Nouns and Verbs”). 


2 The spacing on each line in generated by the system afresh each time a verb's definition is displayed, according to a 
1 Because of Шм, redundant blanks that you may introduce when you enter tbe definition ше discarded 
= y. 
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The system verb Ofx expects an argument in the canonical form. The 
system verb 3 Dfd accepts either the canonical form (as a table) or the 
standard form (as a list with embedded newline characters, with line num- 
bers and opening and closing V). 


Names in the Header 


The header always contains the verb's name. This is the name by which 
the verb is invoked in an APL sentence. In the example, the verb’s name 
is growthrate. 


The header also indicates whether the verb takes arguments and retums а 
result. It does so by supplying names by which the argument and result are 
known inside the definition. When the verb takes one argument, a name for 
the argument follows the verb’s name. In the example, rate is the way 
the verb refers to its right argument. 


When the verb takes two arguments, names for the arguments appear опе 
on either side of the verb’s name. In the example, time and rate are 
names for the two arguments. 


When the verb retums an explicit result, the header includes a name for the 
result. The result (if present) must be the first name in the header, and must 
be followed by the copula. In the example, 2 is a name for the result. When 
execution of the verb terminates, the result retumed is whatever value has 
been assigned to the name shown in the header as the result. 


If the header does not provide for а result, or execution terminates without 
assigning a value to the name that the header designates for the result, the 
verb can still be executed. However, when the sentence that invokes the 
verb tries to make use of the verb’s (nonexistent) result, APL reports а 
result error. Thus, a verb that retums no result can be executed only 
when it is the sentence’s root verb 


Headers for Monadic, Dyadic, and Ambivalent Verbs 


A monad is а verb that takes one argument. ‘The header of а verb that can 
be used only as а monad therefore provides a name for only one argument. 
‘The name for the argument follows the name of the verb. 


An ambivalent verb can be used cither as а monad or as а dyad. A user- 
defined verb whose header provides names for two arguments is ambivalent, 
and may be used with one argument or with two. When you use the verb 
dyadically, you must place its arguments around it, one on each side of the. 


35 For discussion of the root verb, see the sections on order of execution in Chapter 2, “Grammar”, 
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verb. Inside the definition, the values supplied as arguments аге referred to 
by the names shown in the header. 


When you use an ambivalent verb monadically, you place the argument 
фет the verb. Immediately to the verb's left, there must be no noun that 
could be its left argument Inside the definition, the value you supplied 
for the right argument is known by whatever name appears in the header 
to the right of the verb’s name. The name to the left of the verb's name 
is reserved for the left argument. During monadic use, thal name has no 
value. A verb intended for ambivalent use should therefore test for the 
existence of the left argument (as, for example, in line 2 of growchrate). 


Localization of Names 


Except for the name of the verb itself, every name that appears in the 
header is thereby declared to be a local name. In particular, the names for 
the verb’s arguments and result are local names. Inside the definition, those 
names are used to refer to the nouns supplied as the verb’s arguments. 


The names used as labels for lines within the definition are also local to 
the definition. (In the example, monad is a label for line 3, and dyad is a 
label for line 4.) 


A label is а name that occurs af the beginning of a line and is separated 
from the rest of the line by a colon. While the verb is being executed, the 
name has а value equal to the number of the line to which it is attached. 
Thus, during execution of growthrate, monad has the value 3 and дуаа 
has the value 4. Although a label can be used in the same way as any other 
noun (for example, to compute monad*1), йз value is fixed; you cannot 
assign a new value to а label. 


Additional local names may be declared by listing them in the header, 
to the right of the names for the verb and its arguments and set off by 
semicolons. In the example, the names г and t are localized. This means 
that, during execution of growt.hrace, the only visible uses of those names 
are the ones assigned by growchrate. After execution of growthrate 
is complete, all local meanings of those names disappear and their prior 
(more global) meanings - if any — are again visible." 


А noun that is to the verbs left but ia tia argument of а conjunction does not count. For exemple, in the phrase 
a*52 ambiverb x, the number 2 is not available to be the ie argument of ambi verh and so the is bere used 
wom 

‘The name of the verb itself is nor local. ‘You could make it local by inchiding it ю the list in the header or using имэ 
label When you make the verb's own name local to it, you make i impossibla to invoke the verb again until execution. 
from the first invocation is complete. 
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Using the v-Editor 


When you are in immediate execution mode, entering a line whose first 
non blank character is 9 switches you to definition mode. You remain in 
definition mode until you enter a line whose last non-blank character is V. 
(А 9 embedded in a phrase or inside a character constant or a comment 
does not count.) 


What you enter with the V depends on whether you are defining а new verb 
or editing an existing verb definition. 


New definition V zemyverb price; subtotal 

Enter V followed (on the same linc) by the verb's 
header. The header must include the verb's name. It 
should also include a name for the verb's result, its ar- 
gumenta, and its local names (as illustrated above or 
in the example for growchrate). If you are not sure 
of some of these names, you can put in just the ones 
you already know and use the editor to supply the other 
names later. 


Existing definition V myverb 
Enter V followed by the name of the verb (with no 
mention of its result, arguments, local names, eic.). 


Prompts in the v-Editor 


The editor prompts by entering the number of the next line (in brackets). 
‘When you are just starting a new definition, the “next” line is line 1; to for 
a new definition the initial prompt is [1]. For a definition that already has 
three lines, the initial prompt is [4]. 


To the right of the prompt, the editor waits for you to enter the text you 
want on that line, or an editing command. An editing command starts with 
Сог). A line of text whose first non-blank character is something other 
than C, ), or ¥ becomes the definition of the line whose number the system 
displayed at the left 


If you want to change the line number, use can either edit it just like any 
other part of the line, or enter a new line number after the existing line 
number prompt. 
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Editing Commands 
Са) Define (or redefine) line я. 
СА mI x2 ...] Delete lines nl, a2, ... 
con Display the entire definition. 
[xO] Display line я. 
{Ол} Display from line м to the end. 
> Copy the last immediale-execution line. 
co Edit line и. Leaves the cursor at the end of the line. You may 
backspace and overwrite or insert corrections. 


Interpolating Lines Between Existing Lines 


You interpolate a line by giving it an interpolated line number. For example, 
1o insert a new line between lines 3 and 4, enter (3.1) (or any other fraction 
greater than 3 and less than 4). 

While you continue editing, the editor leaves the lines with whatever num- 
bers you assign them. But when you leave the editor (thereby closing the 
definition), the editor renumbers all lines with consecutive integers. 


Once you have entered а line, the editor prompts for the next line in se- 
quence. It does that by adding 1 to the last position used in the line just 
completed. When the previous line had an integer line number, the editor's 
next prompt is 1 more than that. When the previous line was a fraction 
with two decimal places (for example, CS. 023), the editor adds 01. so ils 
next prompt is [6.03]. И may prompt for an existing line number, so be 
careful not to enter an inserted line over an extant one. 


Empty Lines 


Empty (all blank) lines cannot be entered using the editor. Although empty 
lines are accepted within APL functions, they can only be entered using the 
system verbs Ofx and 3 Dfa The editor will, however, allow display or 
deletion of empty lines. 


Syntactically Invalid Lines 


Lines which are syntactically invalid are accepted by both the editor, and by 
the system verbs £x and 3 Dd. Syntactically invalid lines include those 
which contain unbalanced quotes, third alphabet characters not in quoted 
strings, invalid numeric constants, and invalid system noun or system verb 
names. 
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Box-drawing Characters 


The system verbs Оѓх and 3 (fd allow you to enter lines which contain 
the box-drawing characters (Dav(24141112) in quoted strings. The V- 
editor will allow you to display or delete such lines, but does not permit 
their entry. 


Editing Occurs in Real Time 


You cannot "quit" the V-editor, as you usually can do with text editors. 
Each line of the verb is altered as you enter that line. If you have made 
an error in editing a verb, the best approach is lo obtain a fresh copy of 
the verb (perhaps by ) copy from a saved copy of the workspace) and start 
over. 


Closing the Definition 


When you are satisfied with what you have entered, you enter 9 to indicate 
that editing is complete. The character may stand alone, ог it may appear 
at the right end of a line you have just entered. The editor renumbers the 
lines with consecutive integers and creates the newly defined verb. 


When you edit a previously existing verb and change its name by editing 
line 0, closing the definition both creates the new definition and erases the 
old. 


Locking the Definition 


If you exit from definition mode with ¥ rather than V, the definition is both 
closed and locked. The editor rejects an ute mpt to use the V-editor on a 
locked definition with the message defn error. The system verbs Псг 
or Ufd simply retum an empty array as the definition of а locked verb. 
Furthermore, the text of the line will not be displayed in error reports nor 
will it appear in Der. 

The APL system provides no means to unlock a locked verb once you have 
locked it. Jt is prudent to keep somewhere safe an unlocked version of any 
verb you lock. 


Editing Can Prevent Resumption of Execution 


Опе of the very useful features of an APL system is that when a user-defined 
verb encounters an error, execution halts but is not abandoned. You can 
correct the definition and resume execution without having to abandon the 
work already done. (see Chapter 8, “Control of Execution") 
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However, editing the definition of verb while it is being executed (that 
is, editing a verb whose name appears on the state indicator) has some 
risks. It is possible to modify the definition in such a way that you cannot 
resume execution of the verb you edited, or so that it is no longez possible. 
to retum to the verb that invoked it. Problems created by editing а verb 
whose execution has not terminated are lumped together under the name 
state indicator damage. Attempting to resume execution of a verb whose 
definition has been rendered inaccessible or ambiguous is rejected as event 
9, si error. This event can be trapped, but recovery may require cutting 
back the stack (abandoning the more recent work) and resuming from an 
earlier point. (see Chapter 9, “Event Handling") 


Distinguishing Active, Pendent, and Suspended Verbs 


In discussing the effects produced by changing the definitions of verbs 
before they have finished, it is useful to distinguish three situations. A verb 
may be active, pendent, or suspended, Here is what these terms mean: 


Active The condition of the user-defined verb now being executed. 

lus name is at the top of the execution stack. The stale 
indicator (reported by 2 Ows 2) shows no asterisk beside 
its name because it is not halted. 
This із a situation you can never sce from immediate execu- 
tion. Since the V-editor can be invoked only from immediate 
execution, it can never edit the active verb. However, Пех 
and 3 Dfd are permitted to edit the active verb. 


Pendent The condition of a user-defined verb that has invoked another 
user-defined verb. The pendent verb is waiting for the verb 
it invoked to complete execution. When that happens, the 
pendent verb automatically becomes active again. Until then, 
it has nothing to do. It is waiting in mid-line (since it has 
started execution of a line in its definition but has not yet 
completed that line). 


Suspended The condition of a verb whose execution has been halted 

because of an error or interrupt. A suspended verb is marked 
in the state indicator by an asterisk. 
When a verb’s execution is interrupted, the system looks for 
a Осгар expression or Dec to tell it what to do next. If it 
docs not find a trap that covers the event, it displays a mes- 
sage describing the event and reverts to immediate execution 
mode. Now if you execute the command ) s1, you will see 
the verb’s name at the top of the stack with an asterisk beside 
it. 
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Damage to the Active Verb 


It is possible for the active verb to modify itself by a statement that uses 
Ofx or 3 fd. When redefinition changes the line being executed, APL 
reports an sí error. A change is considered to have occurred when, 
following use of Ü£x or 3 Ofd, the line whose number is reported in the 
first item of Dc is no longer identical to the line the interpreter started 
with. That could arise either because: 


+ you actually changed that line 
or 


you inserted or deleted lines ahead of it во that the first element of the 
line counter now points to a line with different content. 


When APL detects such a change to the current line of the active verb, it 
replaces the verb's name in the state indicator by blanks and signals event 
9,51 error. 


Damage to a Pendent Verb 


me name of a pendent verb appears in the state indicator without an aster- 
isk. (The active verb is a special case of a pendent verb.) 


The active verb’s use of Пех or 3 fd may damage a pendent verb in the 
same way as it may damage the active verb itself: by changing the sentence 
to which the line counter points. When the active verb completes execution 
and attempts lo retum control to the pendent verb, the interpreter signals 
event 9, s1 error. 


APL may be unable to resume execution of a pendent verb if you change 
the localization of its name in а way thal makes the verb invisible. That 
can happen in either of two ways: 


» You localize the verb' s name. 
* The verb's name is initially local, but you delocalize it. 


їп either case, APL replaces the verb's name in the state indicator by blanks. 
It leaves Il с unchanged. When the pendent verb completes execution and 
tries to retum control to the verb that invoked it, it finds the name is now 
blank. It signals event 9, si error. 


When work is suspended and the top row of the state indicator contains a 
verb whose name is blank, a branch statement in the recovery expression 
of a relevant It rap (or a branch statement entered from the keyboard) 
causes a normal exit (but with no result). That line is removed from the 
slate indicator, and control passes to the line that followed il. That tine 
may be able to resume — provided it is not expecting a result. 
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This chapter describes how you “run” a program — that is, start the execu- 
tion of a sentence containing a user-defined verb. It describes what happens 
as that verb uses other user-defined verbs and how they refer to nouns to 
pass data between them. It also describes what happens when the program 
encounters an error or is interrupted, how you can make changes or cor- 
rections to the suspended program, and how you can resume work without 
having to start over from the beginning. 


Programming and Immediate Execution 


In its default atate, APL is an interactive system. That is, when you start an 
APL session from a keyboard, the APL system waits for you to type one 
sentence from the keyboard. When you signal that your sentence is com- 
plete (by pressing the Enter key), the APL system interprets and executes 
that sentence and displays its result, Then it waits for you to type another. 


If each of the sentences you type is a small calculation, you get the answer 
immediately; the session is a rapid alteration between question and answer. 


However, the sentence you type may invoke a user-defined verb (or several 
of them, in а compound sentence). The verb's definition may contain up to 
32767 lines. Each of the sentences on those lines may itself invoke other 
user-defined verbs. They in tum may invoke others. Thus a single sentence 
you enter from the keyboard may set in motion a great deat of work. 


А verb's definition consists of a sequence of APL sentences. In principle, 
anything a program does you could also do by entering instructions from 
the keyboard. You could simply enter each sentence, watch it execute, and 
then емет the next. А verb's definition thus consists of a set of sentences 
that you might have entered from the keyboard for immediate execution. 
Instead, you - or someone - entered them earlier and made them part of a 
definition. Perhaps you used the V-editor to accumulate them, or perhaps a 
word processor. Perhaps you acquired the whole set of definitions simply by 
entering the command ) load followed by the name of a saved workspace 
and thereby gained access to any of the definitions stored in it. Perhaps 
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you have a Ot rap set up 20 that cach time you or your program asks for 
something that is not now defined, it retrieves what is needed from a file. 


Once you have the definitions for a program, you instruct APL to execute 
the program simply by including its name in а sentence to be executed. 


Status of Work in Progress 


Each workspace. contains a state indicator and a line counter. Together, 
these show the name of the verb now active and the line of that verb now 
being executed. They also show the verb thal invoked the active verb, and 
the verb that invoked it ~ for as many verbs as are involved. The state 
indicator contains a row for each defined verb whose execution has started 
but not yet completed. k also shows the symbols 4 and O in the same 
manner as user-defined verbs. 


When no user-defined verb is pending, the state indicator is empty. When 
you enter a sentence containing a user-defined verb, the name of the verb to 
be executed goes on the state indicator. At the same time, the line counter 
keeps track of the number of the line that is now being executed (or that is 
ready іо execute, when the interpreter is between lines). 


it. before work on that verb is complete, its definition invokes another user- 
defined verb, that verb's name is added as а new row at the top of the state 
indicator. APL sets aside work on the row below and focuses on the row at 
the top. When it finishes work on that top row, it removes it from the state 
indicator stack and resumes work on the row that was temporarily pushed 
down. 


me command ) si (state indicator) shows the names that are on the state 
indicator stack, commonly just called the stack. You can only enter a 
system command when your task is in immediate execution mode. Thus 
the command ) 53 has something to show you only when work has been 
interrupted, leaving the names of some user-defined verbs on the stack. 
The system verb 2 [ws 2 reports the same information. However, since 
2 Qws 2 does not require a retum to immediate execution, it can report 
what is on the stack as it goes along. To illustrate, consider the following 
two programs: 


9 zeverbl 
[5%] ‘This is verb 1, and here ts si:* 
[2] 2 08 2 
131 2, 
41 zez,verb2 
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¥ zeverb2 
[11 This is verb 2, and here із 81: 
[22 2 Dws 2 
[3)  z«eülc 

v 


When you execute verbi, you sec first the state indicator as it was when 
line 2 of verbl was active, then the state indicator as it was during the 
corresponding line of verb2, and finally the result: 


verbl 
This із verbl, and here is sit 
verbl[2] 
This is verb2, and here is si: 
verb2[2] 
verbi[41 
12 


The result 1 2 is the number of items on the state indicator during execution 
of verbi and verb2. 


Suspension Due to Error or Interrupt 


‘Something may happen thai prevents completion of the execution of a verb. 
Something in the environment may be unsatisfactory (a file is not available, 
or there is not enough space in the workspace). Something needed may be 
issing (a utility verb may be invoked but not present). The definition 
itself may contain an error of spelling or syntax. 


Work may also be suspended by a signal from outside. You can signal an 
interrupt at two levels of urgency: 
Weak interrupt Signaled by а single press of CTRL+break. Requests 
APL to halt before beginning the next line of a user- 
defined verb. 


Strong interrupt Repeating the signal upgrades а former weak interrupt 
on which APL has not yet acted. Н becomes a strong 
interrupt. It requests a halt to processing as soon as 
possible, without waiting for the start of the next line, 
or even for completion of the current line. 


In general, afier encountering an error or receiving an interrupt signal, APL 
stops working on the sentence that is now active. The interpreter checks 
to see whether the condition is provided for in an event trap (described in 
the next chapter). If no trap is provided, APL halts, but does not abandon 
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execution. It notes where il is in the active program. Then it returns to 
immediate execution mode and awaits further instructions. 


You are free to take corrective action and then resume work. Or you may 
do something else for a while and then take corrective sction and resume 
work. Or you may abandon execution of the most recent keyboard entry 
by entering + alone, or abandon all executions by entering ) sic (state 
indicator clear). 


When you save your active workspace, the line counter and state indicator 
are saved as part of it. When the saved workspace is loaded al some later 
occasion, it is recovered as it was, including the state indicator showing 
where it is in the verbs you lef partially executed. If it is appropriate, you 
will be able to resume execution where it was suspended. 


Pendent vs. Suspended Verbs 


А verb whose execution has stopped because of an interruption or an error 
is said to be suspended. 


A verb whose name is in the state indicstor but is not suspended or active 
is said to be pendent. Although it is not currently active, nothing is wrong 
with it; it is simply waiting until execution of the verb that it invoked is 
completed. Execution of a pendent verb resumes automatically as soon as 
execution of the verb above il in the state indicator is completed. 


The result of 2 Ows 2 (or the display produced by ) s1) shows on each 
row the name of a verb, followed in brackets by the number of the current 
line for that verb. A suspended verb is marked by an asterisk, whereas a 
pendent verb has no asterisk. 


The Line Counter 


The system noun Dc returns a numeric vector having one element for each 
row of the state indicator, it contains in numeric form the line numbers 
shown in brackets in the display of the state indicator. 


For a pendent verb, the line number shown is the number of the line now 
being executed. For а suspended verb whose execution was halted by 
an error or interrupt, Oc shows the number of the line the system was 
executing when the error or interrupt occurred. For a verb halted after 
execution of one line has been completed, but before execution of the next 
line has started, О2с shows the number of the line next to be executed if 
execution is resumed in sequence. 

When the system puts the symbol а or О on the state indicator, the corre- 
sponding element of 01c contains the line number of the verb that contains 
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the а or D. When you enter 4 or П from the keyboard (in immediate exe- 
cution), the corresponding element of Ill o contains the line number of the 
most recently suspended verb. However, for 4 when no user-defined verb 
is on the state indicator, Dc contains 0. 


Local Names at Each Level of the State Indicator 


Each user-defined verb may declare that certain names are local to its defi- 
nition. The local names are those used in the header to name its arguments 
and its result, and those listed further to the right, set off by semicolons. A 
verb's line labels are also local. 


However, the name of the verb itself is not local unless that name is cx- 
plicitly repeated in the list of local names, or is also the name of a label, 
an argument, or the result. 


Аз long as a verb works satisfactorily, you never need to now what names 
within it represent its arguments or its result, or what other names it may 
localize. ‘These become significant only when you halt the verb or change 
ils definition. 


The command ) sinl (state indicator with name list) shows the same in- 
formation as ) s1, but lists on each row the names that are localized at that 
level. 


To illustrate the effects of localization, suppose that there exist in the work- 
space three objects called a, b, and с. Suppose that you invoke a verb 
named verbi, whose line 4 invokes verb2, whose line 3 invokes verb3, 
whose line 7 invokes verb4. Suppose that verb4 refers to all three names, 
a, b, and с. 


The definitions are written во that verbl and verb each localizes the 
пате c, while verbs localizes the name b. If you halt execution of 
verb4 (while it is working on line 2) and display )sinJ, it looks like 
this: 

)sinl 
уегЬ4[2) * c 
verb3(7] b 
verb2(3] 
verbi(4] c 


To make clear how localization determines what referent is visible, Figure 
8-1 arranges all names of interest 20 they are aligned in columns. What 
is visible at a particular instant is the view looking downward from the top 
row of the display produced by) sin1. For this purpose, the "global" level 
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is a row below the last row of) аіл], containing all names that are visible 
when no verb is being executed. 


Latest Invoked 


Earliest Invoked 


Figure 8-1: The visible referent of a name is the first appearing in ) sinl. 


As you can see in Figure 8-1, since the name а is not localized by any of 
the verbs, a reference to a in verb4 goes all the way down to the global 
level. 


Since the name b is localized by verb3, a reference to b in verb4 gets 
the b belonging to verb3. The local use of b is said to shadow the global 
b. 


Since the name c is localized by verb4, a reference to c in verbá gets 
the c belonging to verb4, which shadows both the local use in verb! 
and the global c. 


The system verb 5 Ows reports similar information. However, it reporta 
it as a table in which there is a row for cach name and a column for each 
level of the state indicator, You give it a list of names, and it reports the 
status of each name at cach level, plus an extra column for global status. 
(See the description of Ом in Chapter 11, "System Nouns and Verbs”) 


Dynamic Localization 


The localization rule described in the preceding section is known as dynamic 
localization. That is, the names that а verb localizes appear global to the 
verbs it invokes. 


2 Strictly speaking, the bottom row of the figure should also sbow columas for the names verb, verb2, atc, vince thos 
names are visible when no verbe ме being executed. 
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Steps at the Start of Execution of a User-Defined Verb 


‘Arguments are passed to a verb, and results retumed, by value. A verb's 
argument is whatever noun is produced by evaluating the expression to the 
right or left of it. When the syslem starts 10 execute a defined verb, the 
following things happen: 

e APL puts the verb's name м the top of the state indicator. 

+ APL appends a new item to the front of Olc, indicating which line 
in this verb is next to be executed. Initially, this number is 1. Later, 
аз execution of the verb progresses, the number in О1с'а first item is 
revised so that it always shows the line now being processed or ready 
to be processed next. The first member of IIc always refers to the 
verb most recently started, 

. APL prepares names for the values of the arguments. И does not 
matter by what names the arguments were known outside the verb (or 
even whether they had names at all). The names of the arguments are 
local. So are any other names mentioned in the header. 

. APL prepares а name corresponding to each label and gives it a nu- 
medic value indicating the line to which it із attached. A label differs 
from other local variables in that: 

* it gets its value automatically at the start of verb execution 
* its value cannot be changed. 

* All other names appearing in the verb header are local. That is, they 

have no referent until assigned one during execution of the verb. 


Any object outside the verb, but having the same name as an argument, 
result, label, or local name of the verb, is invisible while the verb is being 
executed and is unaffected by any action performed while the vezb is active. 


APL executes the lines of the verb in sequence (or as branch statements may 
direct) until the verb ends, At that point, the value of whatever variable 
was named in the header as the result of the verb is retuned. The first 
element of Ul is dropped and the verb's name is removed from the state 
indicator. The referents of all names local to the verb vanish. The earlier 
(more global) referents of those names (if any) become visible once more. 
1С a previous line on the state indicator indicated а pendent verb, it would 
become active again. 


Example of Argument and Result Passing 


Chapter 7, “Verb Formation” showed a verb growthrate to illustrate the 
standard form of a definition. The left argument was the number of years for 
which monthly compounding continues, and the right argument the annual 
percentage rate of interest. In the definition, the left argument, was called 
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time and the right argument rate. Suppose a verb report contains on 
line 3 the sentence: 


TotaleInvxYears growthrate BaseRatet0.5%16 
As APL starts on this sentence, the state indicator contains: 
report (3) 


In processing the sentence, APL finds that the verb growthrate is 
a dyad. When APL has found the value of Years and the value 
of BaseRatet0.5x16, il invokes the verb growthrate. It leaves 
report{3] pendent while it puts а new verb at the top of the state indi- 
cator. 


If at that point you could see the state indicator with name list, it would 
appear thus: 


growthrate[1] z rate time dyad monad 
report(3) z Total Inv Years BaseRate 


As soon as growchrate is placed on the top of the state indicator, APL. 
reserves the local names you can see beside growthrare(1). The labels 
monad and dyad are given the values 3 and 4 respectively. 


The right argument rate receives as its value the array that results from 
evaluating BaseRatet0. 5x16. 


The left argument t I me is assigned the value of the army Years. 
The name z is given no value; it is reserved for the result. 


Multiple Copies of Arrays Share the Same Space 


In this example, when growthrate is invoked, its left argument is not 
an expression but simply the name Years. Since Years already exista 
and the new name cime is to have the same value, APL simply notes that 
time is the same as Years and does not create a second copy of the data. 
However, if the definition of growthrate subsequently sets а new value 
for time (for example, by a sentence such as time=timex12), APL then 
gives time its own value and no longer refers to the value of Years. 


In general, whenever a name is assigned а value already identified by an- 
other name (for example, in an expression such as x-y«z«^ n), APL creates 
only а single data array and lets all the other names refer to it, rather than 
making many copies of the same array. As soon as there is any change to 
any part of the value assigned to any of the names, APL createa а separate 
copy of the entire object for that particular name. This aspect of internal 
housekeeping ix not directly visible other than by its benefits in reducing 
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the requirements for storage in the active workspace, and a reduction in the 
time required to perform the operation. 

Many expressions in APL involving verbs and derived verbs save time and 
space in this way when their result is the left or right argument. Such 
expressions are called identities. For example, ravel of a list does no actual 
data movement. It takes fixed time and space to execute, regardless of the 
size of the argument. 


Value Returned by the Verb at Completion 


When execution of growthrate is complete, the name growchrate із 
removed from the top of the state indicator and APL picks up where it left 
off in its evaluation of line 3 of report. As growthrate terminates, 
APL notes the name assigned to ils result (in this case, 2). Whatever value 
2 then has is returned to the statement that invoked growthrate. Thus, 
in the example, whatever value z then had becomes the value for the right 
argument of x. 


Branch Controls the Sequence in Which Lines Are Executed 


Unless a branch statement (see next section) modifies the order, APL ехе- 
cutes the lines in а verbs definition one after another in ascending numeric 
order starting with line 1. 

A sentence whose first non-blank character, not counting а label and its 
colon, is the right-pointing arrow +, is a branch statement. 


A branch statement overrides the normal sequence of execution by telling 
APL the number of the line to execute next. A branch can also be used to 
resume suspended execution, either manually from the keyboard or as part 
of an automatic recovery set up by Dt rap (described in Chapter 9, "Event 
Handling”). A suspended verb can be restarted only at the beginning of a 
line (even though the interrupting event may have occurred in mid-line). 


A branch affects only the verb at the top of the sate indicator. 


When execution is suspended, entering a branch statement from the key- 
board causes the verb at the top of the state indicator to resume execution 
at the beginning of the line indicated in the branch statement. 


Form of a Branch Statement 


‘The branch arrow + may stand alone or may be followed by an expression. 
The expression to the right of the arrow is the destination of the branch. 
When evaluated, the destination must be an item or a list. When the list 
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is not empty, its first element must be an integer. APL rejects any other 
value as event 11, domain error. 

The expression to the right of the arrow is usually stated as some function 
of one ог more of the verb's line labels, or 0 (meaning "exit"). However, 
the statement is not required to refer to а label. A label is a handy way 
of referring to a line's number. Labels also improve the maintainability of 
APL programs. 


Result and Effect of a Branch 
Branch is not a verb and does not have a result. 


‘When the destination of a branch identifies an existing line, control passes 
immediately to that line. When the destination is a list having more than 
опе item, йеп after the first are ignored. 


Effect When Destination Is Zero or Out of Range 


A destination that is an integer but is not the number of any line in the 
current verb (typically, 0) forces a normal end to the verb's execution. The 
verb returns whatever value has by then been assigned to the name that 
appears to the left of · in the headers 


When the exit occurs before the result has been given a value, the verb 
returns no result. If the sentence that invoked the verb needs the verb's 
result, the failure to retum а result causes event 8, result error. 


Effect When Destination Is Empty 


During execution of а user-defined verb, branch to an empty destination 
has no effect. The empty branch may arise directly from 


0 
or (more likely) from 
(false condition) / label 


Following an empty branch, execution continues in sequence with the next 
sentence. (On a line with diamonds, that is the next sentence to the right. 
Otherwise, execution proceeds to the line below.) 


When execution is halted, an empty branch does not restart it. 


„ Tbe ryuem verb Ог дпа also wrminaie execution of the active verb, but by forcing an abnormal end. Tbe event 
identifad in is [gna Г» argument i reported . verb. Sae be description of Ooi gral 
ia Chapwe 11, “System Nouns and Verba” nd the discussion of event handling ш Chapter 9, “Event Handling” 
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Branch in Execute 


The foregoing statements about branch remain true regardless of whether it 
occurs within the argument of 4 (execute). Thus 


atedest! 
has exactly the same effect as 


“dest 


Branch in a Line with Diamonds 


The foregoing statements about branch remain true regardless of where the 
branch statement is located within the line. For example, suppose a line 
contains three sentences separated by diamonds and a branch in the middle 
sentence, thus; 

sentencel © «elsewhere 9 sentence? 


When the shape of elsewhere is empty, both sentencel and sen- 
tence2 are executed. But when elsewhere is not empty, sentencel 
is executed and sentence? is not. 


Branch to Resume Suspended Execution 


When а verb has been suspended, the system waits for you to indicate 
what you want done with it. The system does not abandon the suspended 
verb. You do not have to resume execution at once; you are free to start 
execution of any verb whose definition is visible. (lf you do so, those new 
verb calls appear at the top of the state indicator, above the entries showing 
the suspended verb.) 

‘When execution of a user-defined verb is suspended (зо that the suspended 
verb's name is at the top of the state indicator and has an asterisk beside 
it), a branch statement with a non-empty destination causes the active verb 
10 resume execution at the line that is the branch’s destination. The branch 
‘statement that resumes work: 


* may be entered manually from the keyboard 
or 
* may be part of the recovery expression of a trap. 


Generally, when execution has been halted, the expression +01с resumes 
work. Note, however, the effects of a mid-line halt, discussed next. 


Seo Chapter 9, "Event Handling”. 
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Resumption Following a Mid-line Halt 


When the halt occurred between lines (for example, in response to a weak 
interrupt signaled from the keyboard) +01с causes execution to continue 
with the next line in sequence. 


‘When the halt occurred in mid-line (for example, in response to an error 
or а strong interrupt), [IIc contains the number of the line on which APL 
was working. Past of that line may have been executed already. Execution 
always resumes at the beginning of a line. Therefore «(1c resumes at the 
start of the line, even though part of it was already executed before the 
error or interrupt, The caret included with the error display (or in Der) 
indicates how much of the line has already been attempted. Depending on 
what the line contains, repeating it from the beginning may be harmless 
ог may be undesirable, leading to incorrect results. А line written so that 
restarting it from the beginning is always harmless is said to be restartable. 


Naked Branch to Abandon Execution 
A naked branch is a sentence in which the righ!-pointing arrow stands alone, 
with nothing to right of it, thus: 


Execution of the active verb (that is, the verb at the top of the state indicalor, 
regardless of whether it is running or suspended) is aborted, along with the 
entire sequence of verbs that invoked it. 


APL removes from the state indicator the current top row (containing the 
name of the active verb) and any other verbs down to (but not including) 
the next verb marked with an asterisk. 


Clearing the Entire State indicator 


The system command ) з {c completely clears the state indicator. Execution 
of all verbs on the state indicator is aborted 


Branch During C-Input 


A naked branch within C-input acts in the same way as a naked branch 
during execution. That is, the evaluation of П is aborted and so is the entire 
sequence of verbs that invoked О. 


Branch with a destination is not permitted during -input. If you attempt 
it, the system rejects your entry with the message result error and 
reissues the request for О-ілри. 


9 This command was formerly called ) reset. 
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Calculating the Destination of a Branch 
The effect of a branch depends on the numeric value of the destination, but. 
not at all on фе manner in which the calculation is stated. So there are 
а great many different ways to write branch expressions. The following 
examples illustrate only а few possibilities. 
Conditional Branch 


The destination expression includes а label and a test; the result is either 
empty (no branch) or the value of the label. The test yields either a 1 
(condition is true) or a 0 (condition is false). The result of the test selects 
or ignores the value of the label, through compression, reshape, take, or 
drop. For example, to branch to label when a is greater than b could be 
written: 

*(a»b)/label 


A complementary pair corresponding to if and unless can be formed with 
for F and + for unless: 


=(а>Ь)+1аЬе1 Branch to label if a>b 
-(a$b)ilabel Branch to label unless asb 


Conditional Execution of Statements on the Same Line 


When you want to execute work only when a is greater than b, you could 
exit conditionally from the line, thereby executing work only when the 
destination is emply: 


*(a$b)/next 9 work 
next: 
The same effect could be achieved by 
a(agb)/twork" 
which may or may not be easier to read and may be less efficient to execute. 


Multi-way Branch 


Compression or indexing may select from among any number of altema- 
tives. For example: 


(testi, test2, test3)/b1, L2, L3),default 
or 


+(labell, label2, labeli3)(test] 
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Branch with Counter 


A simple loop often combines conditional branch and an unconditional 
branch. The following shows a leading decision that controls n repetitions 
of а tiep called work. h is called a leading decision because the test is 
made before work is ever executed. That allows for the possibility that 
work may be executed zero times. 


1*0 
test: 1+1+1 
( ne 
work 
test 
next: 


(Some people like to combine the test and the increment in а single state- 
ment, for example (ne- I next. However, in that form the slate- 
ment is not restartable.) 


Stop and Trace Controls 


Аз an aid to debugging, you can set stop- or trace-controls for an unlocked 
user-defined verd. The two are independent but controlled by a similar 
mechanism. Stop and trace are effected by a dummy name composed of 
the characters sô or tA followed by the name of the verb. For example, 
to set stops on lines 3 and 15 of a verb called work, you execute: 


Shworke3 15 
Similarly, to trace the execution of all lines of the verb called work that 
has no more than 99 lines, you might execute: 

tàworkei99 
The stop or trace is effective for those lines that actually exist and are 


assigned to the stop- or trace-conirol (so it is not wrong to assign 199 even 
when work in fact has only two lines). 


Each time you set the stop-control for a verb, you thereby remove any 
previous stops. Similarly, each time you set the trace-control for a verb, 
you thereby remove any previous trace-controls. Once a stop or trace has 
been set, there is no mechanism to report the numbers of the lines on which 
it is effective. 


Stops and traces are removed by setting them to an empty vector: 


* You could pass the result of + io another pronoun (and thereby record the values you used) by an expresion such as 
tracede tàvorke199, 
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t&workeiü 
Stop and trace have no effect on locked verbs. 


Effects of Stop 


When APL comes to а line marked with а stop-control, execution halts 
before work on the line is started. The halt is event 1001. The effect is 
much the same as a weak interrupt signaled from the keyboard. That is, 
(provided the event is not trapped) execution is suspended at the beginning 
of the line. APL. displays the name of the verb and the number of the line 
that is next to be executed. 


You may examine the values of names, perform tests, edit definitions, and 
зо on. When satisfied, you may resume execution at the point where work 
was halted by «(1c (or exploit any of the other options available when a 
verb's execution is suspended). 
То permit the restart of suspended verbs, а line branched to from immediale 
execution is not subject to sA. 


Effects of Trace 


For each line for which a trace was requested, as APL completes execution 
of each sentence in the line, it displays a report. For the first sentence on 
each line, the report shows the name of the active verb together with the 
line number Un brackets). For subsequent sentences on the same line, it 
shows a diamond. 


For each completed sentence in a traced line, APL displays the root value. 
For example, in sentence such as 


х+(а+15)х(Ь+22) 

APL reports the value assigned to x but not the values assigned to a or h 
When the root value is an item or a list, it appears on the same line as 
the verb name and line number, or the diamond. When the root value is 
a table (or higher-rank array), the display starts on a new line (to preserve 
the alignment of columns). 


When a sentence has no root value (because the root verb cums no result, 
ог the line is empty), the trace display is blank. 


When a sentence explicitly calls for display, APL first does the display 
in the usual way, and then the trace display as described in the preceding 
paragraphs (so tracing a line that itself produces a display will cause two 
displays). 
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When the traced sentence ів а branch, the trace display shows the right 
arrow followed by the numeric value of the destination. 


Effect of Editing on Trace or Display 


Editing a verb's definition with the V-editor does not affect the stop or trace- 
controls. If you insert or delete lines ahead of the lines that are marked for 
stop of trace, tracing remains with the lines originally marked, even when 
they are renumbered, 


The verbs Ох and з Dd in effect destroy the former definition and create 
а new one, so that editing а definition with either Оёх or 3 Dfa loses all 
of that verb's stop or trace settings. 


Effect of Storing and Retrieving a Verb with Stop or Trace Set 


А verb stored in а saved workspace retains the stop or trace settings it had 
in the active workspace and retains them when the workspace is loaded or 
when the verb is copied from the saved workspace. 


А verb inserted into a package by the system verb Opack retains its trace 
or stop settings and they are retained when the verb is subsequently mate- 
rialized from within the package by the system verb Dpdef. 
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An event is something that disrupts the normal sequence of work and re- 
quires further instructions. 

An eveni may be trapped or untrapped. An untrapped event returns control 
to the keyboard for you to take appropriate action. 


A trapped event is one you have foreseen and provided for. The recovery 
instructions you store as part of a trap definition usually contain the same 
sorts of things you might otherwise enter from the keyboard after the event 
occurs. When they are stored in advance in t гар, the recovery proceeds 
automatically; there is no display of an emor message and no pause to 
receive new instructions. 


Errors and interrupts 
An event falls into one of two main classes: 


Error APL is unable to carry out the sentence it is working on. 

An error may arise for any of a number of reasons. For example, 
it might be because something is inherently wrong with the sen- 
tence itself (perhaps invalid syntax). The data supplied may be 
inappropriate 10 the verb (having the wrong type, rank, or value). 
The sentence may refer to a name that has not been defined. Al- 
tematively, the problem may be that, although there is nothing 
wrong with the sentence, APL cannot execute it because of some 
constraint of resources (not enough room in the active workspace, 
file full, access denied, and во on). 


Interrupt APL. receives а signal from outside the active workspace indicat- 
ing that work should be interrupted. 
An interrupt arises from a signal from the keyboard: you press 
CPRL+break indicaling that you want work halted, or press 
CTRL+c 10 interrup input. 1 


Classifying Interrupts 


An interrupt is classified by what APL was doing at the time it halted 
execution in response to the interrupt. For example, if it was processing 


1 See the description of wrong and weak interrupt in Chaps 8, "Control of Execution”. 
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keyboard input, it calls the interrupt an input interrupt. The term 
interrupt (without a qualifying adjective) refers to an interruption during 
execution of an APL expression that did not involve something external to 
the workspace. 


Weak and Strong Interrupts 


їл processing an interrupt, the system recognizes two levels of urgency. The 
first time you send an interrupt signal, the system notes а weak interrupt. A 
weak interrupt is also called an attention signal. APL takes а weak interrupt 
to mean “Halt before starting to execute a new line.” 


During the interval after you have sent the first interrupt signal but before 
APL has halted work, you may signal a second interrupt. When the system 
detects a second interrupt, it upgrades the urgency of your request and calls 
it a strong interrupt. Following a strong interrupt, APL halts as quickly as 
possible. It is very possible that the halt resulting from a strong interrupt 
occurs in the middle of a line, with some portion executed and some not. 
This may make the line non-restartable, in the sense that side effects may 
have occurred. 


Signaled Errors 


Executing the system verb signal produces the same effect as an error. 
Gs ina! is limited to signaling errors; it cannot signal an interrupt.) In 
particular, signal: 


. Halts execution of the item at the top of the state indicator, that is, of 
the active user-defined verb or a use of 4 or Chinput. It also removes 
the item from the state indicator, causing the signaled error to be made 
visible to the verb which invoked the error-producing item. For a user- 
defined verb, this is equally true regardless of whether: 

* the active verb is running (that is, being executed) 
or 


* the active verb is suspended, and you enter the sentence containing 
Osigna. from the keyboard. 


. Sets Der to indicate the error number specified in the right argument 
of Dsignal. The optional left argument to signa) supplies the 
error text in Der. 


You are free to use any error number between 1 and 999. That is, your use of 
signal may either emulate a standard error (such as 11, domain error 
or 3, index error), от it may signal some arbitrary error unknown to 
APL but meaningful 10 your application. By convention, a user-defined 
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error is given a number between 500 and 999, whereas no system-generated 
error has а number in that range. 


One reason for signaling a user-defined error is that you plan to trap it and 
thus provide automatic recovery from some condition that your application 
has signaled. 

When Ils igna ! із used from within execute, or from within D-input, the 
top line of the state indicator contains 4 or O. Then 1 or П is removed from 
the top of the state indicator (not the user-defined verb that contains it), and 
the event is signaled to the next level. Thus the effect of а "Озі опа n* 
is not the same as the effect of Msignal n. 


Trap, Action, and Recovery 


An event trap is a list of instructions whose effect is to say to APL, “If the 
following occurs, here is what to do.” The trap specifies what event (or 
events) to look for and an action code specifying whal action to take when 
опе of them occurs. 


You write these instructions by setting the value of the system noun It rap. 
As soon аз you set a value for It rap. APL verifies that Ut rap contains 
а valid action code and well-formed event numbers. (If APL finds your 
Осгар ill formed or otherwise invalid, it resets It rap to be an empty list.) 
Apart from that initial check for an ill-formed trap, setting Qt rap has no 
effect until а trappable event occurs. Then APL looks in the various values 
of Ut rap for an event number that matches the event that has occurred. 


When you set It rap. you may supply any number of separate statements. 
about events and actions. See the description of Осгар in Chapter 11, 
“System Nouns and Verbs”. 


Unreportable or Untrappable Events 


Certain events are outside the scope of the event handling mechanism. In 
particular, nothing that occurs during execution of a system command can 
generate a reportable or trappable event. 


An error directly encountered during execution of a recovery expression 
is not itself trappable. This restriction prevents endless recursion from 
certain defective Ut rap expressions. However, even with this feature, 
it is still possible to construct event handlers that execute endlessly, so 
prudence is called for in their creation. Furthermore, errors occurring during 
the execution of a user-defined verb invoked by a Псгар expression are 
trappable. 
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Event 2001 (retum to immediate execution) is not reportable — that is, docs 
not set а new value for Der, even though it is а trappable event. 


Events 67 and 68 (certain system errors) are reportable — that is, do cause 
бег to be set, even though it is not feasible to do anything about them, 
They are not trappable, except when generated via Dsignal. 


An event arising during execution of а system command is never reported 
in Jer and cannot be trapped. 


Environment Condition Prohibits Suspension 


‘There arise cases in which you do not want a verb to be suspended. For 
example, in a shared nouns application, you do not малі to permit one user, 
by interrupting a verb, to tie up another user. To preserve the security of 
data in a shared file, you do not want a user to be able to examine nouns 
before the verb has completed its processing. One way to prevent a verb 
from being suspended is 1о trap the events that might suspend it. However, 
such а trap can take effect only when it has been set and only when its 
recovery expression deals successfully with the event. Suppose the event 
occurs in the interval after the verb has started execution but before a trap 
has been sel. Suppose that when the event occurs, it is something for which 
the trap makes no provision. Dec (for environment condition) provides а 
more certain means to prevent suspension. 


Uec is a system shared noun. That is, it is always shared with the APL 
system, and APL can set it In particular, APL always sets Пес so that 
it is never without a value. Within any verb to which Пес is local, APL 
immediately sets ils value to 1. The verb may then contain a statement 
such as Пес+0. However, it is not necessary lo set a initial value Пес«1 
because merely by making Пес local, you direct APL io set it to 1. 


Within a verb whose definition localizes Dec, there is no interval during 


which an event could occur before the verb has had lime to set Пес to 1, 
since it automatically has that value by virtue of being localized. 


Effect of 1 as the Value of Dec 
As long as the value of Dec is 1 at any level of the state indicator, a user- 
defined verb cannot be suspended unless the current line is one for which 
the så stop-control has previously been set. Thus, unless stop-control has 
been set, an event must either: 
* be successfully trapped 
or 


* cause the active verb to be abandoned, and the event signaled to 
the environment that invoked it. 
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Consider the behavior of a verb foo, whose definition is as follows: 


V 2+4 foo € 
(1) ze 


When a is 0 but w is not, the arguments are outside the domain of +. That 
is a domain ejror. How APL responds to that event depends oa the value 
of Dec, as follows: 


Qeceo Dece1 
0 fao 12 0 foo 12 
domain error domain error 
fooll) 2 0 foo 12 
A ^ 
?зі )si 
foot11 


When Dec is 0 (its defauh value in a clear workspace), the verb foo halts 
оп line 1, and the error report points to the symbol +. But when Dec is 1, 
execution of foo is halted. The event is still reported as domain error, 
but is attributed to foo rather than to a sentence within it 


To set Dec globally to 1 is usually more protection than is needed. Instead, 
you may set it to 1 only for some critical section of a definition. That can 
be achieved by a sequence such as the following: 

(1 [nonscritical work. 

1 QUecti 

1 critícal sectíon 
Nec 

1 (mor non-critical work ..] 


Values of Dec 


Пес is binary: you may set it only to 1 or to 0. In a clear workspace, the 
default valueiof Dec is 0. If you set it to anything other than an item 1 or 
0, APL resets it to 0. 


Dec · 1 in the SI Stack Prohibits Suspension 


Like (trap, Пес has the important property that APL does not consider 
only the visible (that is, most local) value, but алу value, at any level of 
the state indicator. As long as any Пес has the value 1, the only untrapped 
event that can cause execution to be suspended is a stop-control, set prior 
to the event by sô. 
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‘To visualize the effects of Пес and It zap at various levels, consider the 
diagram in Figure 9-1. И assumes that verbl invokes verb2 which 
invokes verb3 which invokes verb4. Since the state indicator shows 
the most recently invoked verb at the top. verbal is shown at the top and 
verbi at the bottom. An additional row at the bottom shows the global 
environment before verbl was invoked. 


The column at the center indicates where Пес has been localized and shows 
the values to which it has been sel. The column at the right shows the 
effective value of Dec. The behavior of Dec is unlike that of any other 
name. While the value of Оес is 1 at any level of the state indicator 
(regardless of whether it is explicitly set to 1 or has the value 1 by default), 
its effective value at all higher levels of the state indicator is 1. Thus the 
effective value may be controlled by a Dec that the higher levels can neither 
see пог set. (Compare Figure 9-1 with Figure 8-1; the 1 in the Dec 
localized by verb? is effective despite being masked by those localized in 
verb? and verb4.) 


Latest invoked 


Earliest invoked 
Global 


Figure 9-1 : Effective value of Dec is the maximum Dec. 


Since Пес is localized by verb2, no event can cause suspension in it or in 
verb3 or verb4, regardless of how verb3 or verbá may set their own 
local values of Пес. 


Response to an Event When Stop is Prohibited 


What happens when a verb that is not allowed to stop does not know how 
to continuc? 


During execution of a verb v in an environment where the effective value 
of Dec is 1, an event has the following effect: 
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Stop Control Halts execution in the usual way. 

(event 1001) 

Weak Interrupt APL notes the interrupt but postpones acting on it until 
(event 1002) the effective Пес becomes 0 (which might not be until 


it completes execution of the verb that localized the 
effective Dec), As a consequence, а weak interrupt 
has its effect on the verb that invoked v rather than 
on v itself. 

Although delayed, the weak interrupt has been noted; 
a second interrupt signal can still upgrade il to a strong 


interrupt. 

Error or Strong Execulion of v is halted, and the error that occurred 
Interrupt in vis instead signaled to the verb that invoked v. 
(except event 

1001 ог 1002) 


What Happens When an Event Occurs 


When АРІ, detects ап event (that is, an error or an interrupt), it does the 
following: 

Notes the event for Der Eventually, APL records the event in Der. However, this 
record goes into the Der visible at the level at which the 
event is handled. If the event is re-signaled to the next 
level (because stopping is not permitted at the present level), 
the note of the event is carried with it, as many times as 
necessary, until the level at which there is a suspension or 
the event is finally trapped. 


Checks Ut rap APL searches the visible (that is, most local) value of Ot rap 

for a trap that covers the event number just encountered. It 
searches Ut rap from top to bottom, lef to right. The бга 
trap which covers the event is used. 
When the [It rap being searched contains a trap stalement 
that applies to this event, APL, carries out the indicated recov- 
ery action. If that is sufficient to resume execution, execution 
resumes and there is no further consideration of Псгар or 
Dec. 


Checks Dec When no applicable trap is visible, or there is one but ite 
execution does not cause a resumption of execution, APL 
checks the value of Пес at every level of the state indicalor 
from the current level down. If Dec is not 1 at any level, 
execution halts. 
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Checks further 


Exit 


if dec anywhere is 1, APL takes the exit procedure described 
below. 


When no relevant trap has been found but [lec is everywhere 
0, APL digs deeper in ils search for an applicable [Ir rap. It 
examines the next level at which Ut rap has been localized. 
If at the next level it finds an applicable trap that resumes 
execution, it takes that action. But if it does not find one, it 
repeats the cycle, considering the next level at which Ot rap 
has been localized, until it reaches the global Ot rap value. 


When at any of the levels checked: 
» the event has not been handled by a trap 
and 
. бес anywhere in the state indicator has the value 1, 


APL abandons execution of the verb at the top of the state 
indicator and signals the same event to the verb that invoked 
it (that is, the verb next below it on the state indicator). 
This new event starts the examination of trap and environ- 
ment all over again, possibly cascading further down the 
state indicator, and possibly reaching a level at which Dec 
is no longer 1. 


Hatt Only when it has checked back through all levels of the state 


indicator, and at each level has found no applicable trap that 
resumes execution, and has worked down to a level at which 
Cec is no longer 1, does APL suspend work with a message 
describing the event. 

Then АРІ. sets Dex with the event number passed back 
through the various levels. The event number is that of the 
original event. However, the event is attributed to the verb 
in which the event was most recently signaled. When there 
was а cascade of events because the original event took place 
ы a level where stopping was prohibited, that information is 
discarded; only the most recent level shows. 

Once execution stops, you may edit the definition of the 
pending or suspended verbs (see Chapter 7, “Verb Forma- 
tion”), restart or halt the suspended verb, or enter a new 
sentence for execution (see Chapter 8, “Control of Execu- 
tion”). 


3-8 Event Handling 


February 1993 


SHARP APL Reference Manual 


Caution: Trapping interrupts or Prohibiting Suspension 


Prohibiting suspensions can make debugging difficult, since it becomes 
impossible to see where the precipitating event took place. However, it is 
relatively simple to use no Dec in the main body of definitions, and set 
Dec to 1 only in an outer verb which invokes the others. 


Since Dec is in that case global to the verbs that do the work, if you do not 
wish users of your application to be able to suspend it, you must preveni 
them from setting stop controls on your verbs? You can do that by locking 
the definitions, or by making their names local to the calling function and 
reading them from a file during execution (зо that they have no global 
existence in the workspace). 

‘Trapping interrupts is sensitive. Interruption is the means by which a pro- 
gram's user ot designer reasserts control when things are going wrong. You 
may trap interrupu in order to achieve a more graceful recovery, but be 
aware that a program in which interrupts have been trapped improperly may 
be impossible to stop. 


Caution: After Suspension, Ot rap Is Still Active 


When you have control at the keyboard, but there is a suspended verb 
оп the state indicator, even though APL did aot find а trap for the event 
that caused execution to suspend, Пс rap is stili there and may respond to 
errors in what you enter now. If you emer а new error and the new error 
is trapped, the recovery expression may abandon the suspended verb or 
resume the suspended verb's execution. 


When you want to experiment following an error, it is prudent to save the 
visible t rap and reset it temporarily to something that causes all events 
to behave as if no Dcraps were present (for example, Dt rap - s!). 


1  Báiing the definitions (for inci Qucz) would maka а Лена саду И your application hat ao 
than а single level of oc localization, во that the visible Пас waa the only е: кш d 
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The component file system provides access to files that contain APL nouns. 


Concepts of APL Component Files 


Components 


An APL file is made up of components. The APL file system transfers data 
between a file and the active workspace one component at a time. 


Each component of an APL file is а noun. Like a noun in a workspace, a 
component may be an array of any rank (item, list, table, higher-dimensional 
array); its data may be of any type (numeric, character, boxed, or package). 
A file may contain the definition of a user-defined verb either as its character 
representation or as the referent of a name in а package. 


Each component may be of any size. Moreover, when you replace the noun 
stored in a particular component, the replacement may also be of any size. 


indexed Access 


A component of a file is identified by its component number, Component. 
numbers are consecutive positive integers, ranging from the number of the 
first component up to the number of the last component. Components are 
numbered in l-origin, so that the lowest possible component number is 
component 1. 


File Size 


‘There is no limit to the total size of а file other than that imposed by the 
physical limits of the system thal contains it. 


A common use of files is to partition data into components that may be 
processed serially, to reduce the amount of data in the workspace al a 
given moment. In similar fashion, a large application may partition the set 
of definitions it uses into those required at different phases of the work. A 
master program reads in the definitions needed for a particular phase, and 


1 The fen component із initially companent 1. However, if ‘some components from the beginning of в fie, those 
Та и re br ере wil ben b e ber her lan T. 
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then, when they are no longer required, replaces them with those needed 
for the next phase. 


File Reservation 


When an APL file is created it is given a file reservation. If the file's size 
exceeds its reservation, APL will not permit you to append components or 
to replace existing components with larger ones. APL will accept a change 
that takes the file past its reservation. You can “resize” a file to set anew 
limit. 


File Primitives 


А component file is manipulated by primitives that you can enter at the 
keyboard or execute from within an APL program. Each of the file primi- 
tives is a system verb, written with a name whose first character is (1. They 
are summarized in this chapter and described individually in Chapter 11, 
“System Nouns and Verbs”. 


Tying Links a File to the Verbs that Use It 


To make use of a file, you must first tie й. APL can have several files 
tied at the same time. The tie verbs Ut te and Ust ie pair the name of a 
file with an arbitrary positive integer called the tie number, While the file 
remains tied, you identify the file not by its name but by its tie number. 
On a single user system, the verbs Ut ie and Ost {e have the same effect. 


Duration of a File Tie 


Once you have tied it, a file remains tied until you erase it with Derase, 
unsie it with the Qunt te, or the session ends. 


A file tie is nor affected by changes to the active workspace; in particular, 
it is unaffected by such actions as clearing the active workspace or loading 
а saved workspace. 


File Access Controls 
Each file has an access table. The access table has three columns. 


User number (column 1) User numbers are not supported in single user 
systems and the value 0 should be used to 
indicate “any user’. 
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Permission code (column 2) A number to indicate which file verbs may be 
used when tied with the passnumber in col- 
umn 3. 


Passmumber (column 3) An arbitrary integer supplied both when ty- 
ing the file and as part of the argument of 
most verbs used with the fle. Passaumber 0 
is equivalent to "no passnumber." 


The access table may provide more than one way for a user to tie a file. 
For example, a user might be granted "read only" access when tied with 


passnumber 12345, 


but “read and replace” access when tied with 7863. 


‘The effective permission is the one corresponding to the first occurrence 
(scanning from the top) of the passnumber used 10 tie the fle. A task 
cannot tie the same file in more than one way at one time. 


The list of permitted verbs is encoded as an integer, called the permission 
code. Each of the separate permissions is a power of 2. The overall 
permission code that appears in a file's access table is the mim of the codes 
for the permitted actions. The number “1 ia used to mean "any verb”. 
Figure 10 ~1 shows the values for the separate permissions. 


Access Control Values in Base 2 Base 10 


0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 


0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0001 
0010 
0100 
1000 


0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0001 
0010 
0100 
1000 
0000 
0000 
0000 
0000 


0000 
0000 
0000 
0000 
0001 
0010 
0100 
1000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 


0001 
0010 
0100 
1000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 


71 Gives unlimited access. 


Permissions Granted. 


Dread, Osize 
t ie 

Пегазе 
Dappend 
Greplace 
drop 

Ohold 
rename 
Ordac, at ac 
Draci 
Oresize 
Ofhola 
Ordac 

Ostac 
баррепаг 
se 


Figure 10-1 :Table of file permission codes. 
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Summary of File Verbs 


Full definitions of each of the component file verbs are in the alphabetical 
list of system nouns and verbs in Chapter 11, “System Nouns and Verbs”. 


Dappend Append component. 


Dappendr Append component and reium component number, 


Davail File system availability. 
Ucreate Create file. 
drop Drop components. 
Оегазе Erase file. 
Ofhoid File hold. 
Оло2а File hold. 
D1ib Directory list of files. 
names Names of tied files. 
Олитз Tie numbers of tied files. 
Urdac Read file access table. 
Огасі Read component information. 
Oread Read component. 
Drename Rename file. 
replace Replace component. 
Oresize Resize file. 
Dsize Size of file. 
Dstac Set access table. 
Ustie Share-tle file. 
Ocie Tle file. 
Quntie Untie files. 
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System Nouns and Verbs 


System verbs are primitives without symbols. They are primitive in the 
sense that they are “built in,” and need no definition. However, unlike the 
main body of primitives, they have not been assigned symbols, Instead, 
each has a fixed distinguished name that starts with the symbol O (quad) 
or M (quote-quad), possibly followed by some letters. For example, Осг 
retums the canonical representation of a user-defined verb. Since you are 
not permitted to use О and Û in user-assigned names, these distinguished 
names are distinct from any names you could give to user-defined objects. 


System nouns are names that are always shared with the APL system. You 
can refer to their values, but so can the system. Like system verbs, the 
systems nouns have fixed distinguished names. The system attaches special 
significance to cach. For example, Oto establishes the index origin (which 
may be 1 or 0), and Dpw establishes the page width for displays. 


Certain system names report the current value of system statistics. For 
example, Ots conlains the timestamp, reporting the date and time, and 
Dai contains accounting information regarding the current user. For most 
purposes, it is moot whether these names denote nouns, or verbs that take no 
argument. This manual describes them all as nouns. Figure 11- 1 indicates 
which you can set, 
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System | You 

Noun Set 

Dai — | Accounting information 
Dav — | Atomic vector 

Oct Yes | Comparison tolerance 
Dec Yes | Environment condition 
Der Yes | Event report 

Ofe Yes | Format contro! 

Oto Yes | Index origin 

oi Yes | Latent expression 
nic — |Line counter 
Unames | — | Names of tied files 
Onums — | Numbers of tied files 
Opp Yes | Printing precision 
üps Yes | Position and spacing 
Ор» Yes | Page width 

Ori Yes | Random link 

Osc Yes | State change 

ts — | Timestamp 

Cerap | Yes | Trap expressions 

Qui — | User load 

Owa — | Work area 


Figure 11-1 : System nouns, indicating which you can set. 


Results of System Verbs 


A few of the system verbs retum no result (and do their work as side 
effects). 
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Alphabetical List of System Names 


Dai 


Accounting Information 


System noun [Jai provides accounting information. This is not imple- 
mented and returns 9P0. 


Dappend 
Append Noun to Tied Fite 


Noun Dappend m {, рт] 
Dyad Dappend writes Noun as a new component appended at the end of 
the file whose tie number із fn. 


Noun is any noun to be appended as a new component at the end of the 
file. i is the tie number to which the file is tied, followed by a passnumber 
pn (if you used а passnumber when you tied the file). 

Effect: Provided that the number of bytes the file already occupies does not 
exceed the file's size limit, a new component is appended. That component 
contains the noun а together with its description, which indicates type, rank, 
and shape. 

File permission: 8. 

Result: None. 


llappendr 
Append Noun to Tied File with Result 


Nous Üappendr  [, ри ] 


Dyad Dappendr writes Noun as а new component appended at the end of 
the file whose tie number is ін. 


File permission: 16384. 
Result: An integer item whose valuc is the component number of the new 
component. 
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llarbin 

Arbitrary Input with Arbitrary Output 
Qarbout 

Arbitrary Output 


Monads Darbin and Darbout have different definitions on different sys- 
tems and are not documented here. A special use of lar bout in input 
is the same on all systems and is documented in section “Discarding the 
Prompt” in chapter Chapter 3, “Nouns and Pronouns”. 


Dav 
Atomic Vector 


The noun Пау is a list of all possible character values in the APL system, 
in numeric order of their intemal encoding, from hex 00 to hex FF (decimal 
0 to 255). 


А common use of Dav is to provide a reference for translating characters 
to their numeric equivalents, for example 


Davi 


or to translate from one character encoding to another, by an expression 
such as 


NewAlf(Daviold) 


To avoid loss of information, Mera I should be a permutation of lav; 
that is, a list in which each of the 256 possible characters occurs exactly 
once. 


Qavail 
File System Availability 


Monad Cava I! reports whether the APL component file system is available 
for use. The only acceptable argument is an empty list. 


Result: The Boolean item 1 if the file system is available for use. Other- 
wise, a Boolean item 0. 


bounce 
Terminate Task 


Monad bounce takes any scalar argument and terminates APL. 
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Dcr 


Canonical Representation 


Monad Dor riums the representation of the most local definition of the 
verb named in its argument. The result is a character table containing the 
definition of the verb in canonical form; that is, without leading or trailing 
del symbols (9) or bracketed line numbers. Each line (including the header) 
is flush-left. Lines shorter than the longest are righi-padded with blanks. 


‘When the argument contains a well-formed name but the visible referent of 
the name is not an unlocked user-defined verb, the result is an empty table 


with shape 0 0. 


create 
Create a File 


fn create i» 


Dyad [create creates а new file with name fn, and share-ties it with fa. 
im must be a positive integer less than 2°! that із not already in use as a tie 
number, 
For example: 

michigan! Ocreate tfn 


fn is а character list containing a file name that is both valid (that is, well 
formed) and available (that is, not already in use). The rules for valid 
names may vary from system to system and are documented in online 
documentation. 


Effect: A new file with no components is created and share-tied to the lie 
number in the right argument. 

File permission: None. 

Resuli: None. 
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Oct 
Comparison Tolerance 


‘The system noun Oct establishes the maximum relative difference allowed 
between two numbers if they are to be considered equal. Comparison tol- 
erance permits the interpreter to ignore small differences between numbers 
likely 10 arise from inexact internal representations that are inherent in 
computer arithmetic on numbers that are not integers. 


Some numbers are inherently incapable of exact representation (for exam- 
ple, т, е, 72). Other inexact representations arise because input and display 
are normally in base 10, but intemal representations are in base 16. For 
example, the representation of 0.1 in binary is an endless sequence of bi- 
nary digits, even though it is finite (and short) in base 10. Yet others arise 
from rounding errors, when numbers that do in principle have finite repre- 
sentations must be truncated to fit within the system’s word size. Tolerant 
‘comparison permits reasonable identities to work even when the system is 
incapable of representing them properly. Thus, the expression 
1 = 3x43 


is reported as true, despite the fact that 3 times the reciprocal of 3 does not 
really produce an exact 1. 


In a clear workspace, the default value for Осс is 1.41969769е 14 
(computed as 1023х16%714). You may assign the visible Det to be any 
numeric item not less than 0, and less than 16-5. Before you set Oct 10 
zero, it may be rewarding to consider the effects of intolerant comparison 
in the example shown in Figure 11-2. 

А way to get exact comparison without setting Oct to zero is by comparison 
with zero. Instead of x with Oct -O. use 0=х-у. 


Verbs Affected by Oct 


The visible value of Oct is part of the definition of the following verbs 
when an argument is represented intemally in floating point or complex 
form.! 


Dyas: | луєл S > є 
Monads: 1 Г # 


Gcr is а relative comparison tolerance. When two numbers are compared 
and at least one of them is a floating-point number, their relative difference 


1 The maximum permined value of (ict is chosen so that (ct could never affect tbe outcome of say of these verbs when 
applied to the arguments that could be imernally represented ee ingen. 
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(which depends on their magnitudes) is compared against Oct. Two num- 
bers are considered equal if their relative difference is less than or equal to 
Det. That is, а and w are judged equal when: 


(Ja) s Oeex( jaf (Iw) 


When one of the arguments (say, ш) is 0 but the other is not, that inequality 
reduces to: 


(Ia) 5 Oct x fa 


Since Oct must be (much) less than 1, the inequality can never be satisfied. 
Thus the value of Oct can never affect a comparison with 0. 


When Oct is 0, all comparisons are exact. The judgment “not equal” may 
be produced by bits that would otherwise be considered insignificant 


Figure 11-2shows how the results of some simple expressions depend 
upon the value of Oct. 


epsel 


Uct*10xeps 


Oct+l0xeps 


Oct 
Det · Ion eps 


Octo 
det · loc eps 


— е 
"o 


Figure 11-2 :Tolerant and intolerant comparisons. 
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The following illustrate the effects of Oct in a few simple examples: 


Пс 
1.413697693е714 


ка+а06 


а=6 


Га 


а-6 
72.220446049е716 


Idi 


Delay Execution 


Monad 041 delays execution of the statement in which it appears. w is a 
numeric item, specifying the duration of the desired pause in seconds. The 
result is a numeric item, the actual delay in seconds. 


When the delay completes normally, the result is not less than w. The 
actual delay (reported as the result) may be slightly more than requested. 
For example: 


Odi 10 
10.033 (Appears about 10 seconds after pressing 
Enter on the line above.) 


Behavior of Delay When Interrupted 


The delay produced by Ud! can be cut short by a weak interrupt. As 
usual, a weak interrupt halts execution at completion of the end of the line 
being executed. The weak interrupt causes Dd! to retum its result without 
further waiting. When the system has completed execution of the entire 
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line, execution halts before starting a new line. (A weak interrupt on a line 
containing multiple instances of 021 cuts short all those that have not усі 
delayed.) 

Since a weak interrupt causes an immediate retum from 002, a definition 
for strong interrupt does not arise. 


Odrop 
Drop File Components 


Monad Оагор ш drops components from the beginning or end of a tied 
file. The argument is: 


drop tw,» l. pn 
in Tie number of a tied file. 
A Number of consecutive components to drop. A positive number counts 
from the beginning, a negative number from the end of the file. 
ра The passnumber, if the file was tied with a passnumber. 


Effect: The indicated number of components is dropped from the file. You 
can drop а block of consecutive components either from the beginning or 
from the end of а file, That reduces the range of valid component numbers. 
Suppose a file has 100 components, numbered from 1 to 100. If you drop 
the last 10, it will then have 90 components, with numbers running from | to 
90. But if you drop the first 10, it will have 90 components numbered from 
11 to 100. Dropping components from a file does not alter the numbers by 
which you refer to the components that remain. 


If you attempt to drop more components than exist, the system rejects the 
expression with the message file index error. 

File permission: 32. 

Result: None. 
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Пес 
Environment Condition 


The system noun Qec is part of the event trapping apparatus. Its value is 
restricted to a Boolean item. When its value is 1 at any level of the state 
indicator, an untrapped error in a defined verb causes an exit from the verb 
(whereas otherwise execution would halt). However, а stop contro? still 
halts execution in the usual way. 


As illustrated in the right side of Figure 11-3, when Пес is set to 1, upon 
encountering an error, APL exits from foo and attributes the error to the 
verb foo as a whole, rather than to a specific statement within it. 


Example with Пес set to 0: Example with (lec set to 1, or lo- 
calized but not set: 

ч foo; Пес Y foo; Пес 
[11 Leco [1) Пес+1 «Can omit this 
[2] 2+ ^ Emor (2) 2+а Eror 

v v 

foo foo 
syntax error syntax error 
toolz] 2+ ^ Епог foo 
^ ^ 


Figure 11 —3 : Behavior of errors depending on Пес setting. 


Dec is a system shared noun. That is, itis shared with the APL system, and 
the system may set its value. In particular, whenever APL starts execution 
of a verb whose definition localizes the name Пес, APL immediately sets 
Dec to 1, As a consequence, when Dec appears in a verb's header, there 
is no way to interrupt it in а way that leaves it suspended until the verb 
itself has set Dec to 0. 


When Dec has the value 1 (either because it has been explicitly set, or 
because APL has set it because it is localized), any verb invoked within the 
verb to which Dec is local is also affected. Moreover, this extends to all 
verbs that may be invoked, regardless of level, and regardless of whether 
they localize Пес. Once an outer verb (that is, one that appears lower in 
the state indicator) has localized Dec, a verb can halt only when: 


» The visible value of Dec and also the value of Dec at ай levels of the 
stale indicator are 0 


31 For a verb v, the expression sÀven set sope on фе lines of у whose line sumbers are members of п. 
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or 
+ A пор control is set for one of the verb's lines and event 1001 (stop) 
is not trapped. 
Sec also Chaptez 9, "Event Handling". 


Der 
Event Report 


This noun is set by the interpreter whenever an error, interrupt, or other 
such event occurs during the execution of a program. You (or the recovery 
expression contained in It rap) may then examine Пег, perhaps just to 
display it, or to decide on remedial action. 

When Der is localized, the Der that is set is the one visible at the level 
al which the event is handled. When the event is trapped and the recovery 
expression uses action c to cut back the stack, or when Пес is 1 so that 
a halt is not permitted, the error report appears not in Der of the level at 
which the event originally occurred {which may no longer exist), but at the 
level of the effective trap (when the event is trapped), or the level at which 
execution halts (when the event is not trapped). 


In general, Der is a table with three rows. It has a fourth row when the 
event is 6, value error, and the event has been trapped with action 1 
(immediaie). The rows contain: 


Oer[1;14] The event number, in four characters, right justified. Figure 
11-4 contains a list of the event numbers that are currently 
generated by APL. 


SiBert1;J The event title, For events signaled by APL, this is the stan- 
dard name associated with the event (see Chapter 9, “Event 
Handling"), as modified by the current setting of )n1t. An 
event signaled by signal may have its own event title, 
specified by the left argument of Osignal. 


Оегс2;) The sentence being executed when the event occurred. 
Der(3;23 Caret pointing to the part of the line being executed when 
the event occurred. 
dert a:) The name that lacks a value (when event 6 has been trapped 
with action i). 
When the workspace is so full that there is insufficient room for an appropri- 
ate Der, APL makes Der a four-clement list containing only the character 
representation of the event number. 
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1 Workspace full 
2 Syntax error 

3 Index error 

4 Rank error 

5 Length error 

6 Value error 

7 Format error 

8 Result error 

9 State indicator error 
11 Domain error 
15 Symbol table full 
16 Nonce error 

18 File lie error 

19 File access error 
20 File index error 
21 File full 

22 File name error 
23 File damaged 
24 File tied 


26 File system error 

28 File system not available 
29 File library not available 
30 File system ties used up 
31 File tie quota used up 
32 File quota used up 

33 File reservation error 

34 File system no space 


38 File component damaged 
45 Workspace locked 


25 File system hardware error 


46 Workspace not found 
47 Workspace not readable 

67 Swap error, clear workspace** 
68 System error, clear workspace** 
72 Interface quota exhausted. 

73 No shares 

74 Interface capacity exceeded 

75 Share table full 

76 Processor table full 

77 Identification in use 

78 Opp error 

79 Ори error 

80 Dio error 

81 Or! eror 

82 Oct error 

83 Oħt emor 

84 Ops error 

85 Ofc error 

95 Workspace not writable 


1000 Any intemupt'** 


1001 Stop 
1002 Attention 

1003 Intezrupt 

1004 Input interrupt 

1005 Shared name interrupt 
1006 File interrupt 

1007 File backup interrupt 


Workspace State 
2001 Retum to immediate executione" 


* 1-999; 0 never occurs in Der. 
** No way to respond, but — briefly — reported in Der. 
*** 1001-1999; 1000 never occurs in Der. 


sm Not reported in Der. 
Figure II-: Event numbers. 
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Llerase 
Erase a Tied File 
fn Gerase IL, p) 
Dysd Qerase erases the file tied to ін whose name is fw, with optional 
passnumber pa. 
For example, if file dat af II e was tied to dfn, it is erased by the expres- 
sion: 


‘datafile’ Derase dfn 

‘The left argument is redundant: all this information is available from the 
tie number. However, the system requires you to provide both forms of 
identification to make it less likely that you will inadvertently erase the 
wrong file. 

Effect: The file ceases to exist, The number formerly tying it is again free 
for use. The file's name disappears from the result of Qnums, Qnames, 
and Olib. The APL system marks the space the file occupied as available 


for other use, 
File Permission: 4. 
Result: None. 
Dex 
Expunge Objects 


Monad Dex expunges (that is, erases) from the active workspace the most 
local referent of cach of the names in its argument. w may contain zero or 
more names, arranged as a table with опе name per row, or as а character 
list or item when there is only one name. 

The result is Boolean list, with onc element for each name in the argument. 
Each element of the result contains: 


1 When the corresponding name is now free (either because it had 
no referent or because its former referent has been crased). 


o When the corresponding name is not free (either because it has а 
referent that cannot be erased, or because it is not a well-formed 
name). 


Dex does not erase a name whose referent is в label or a system noun or 
verb. A verb that is executing, pendent, suspended, or waiting cannot be 
erased. 


If Gex produces а ws ful] or domain error, nothing has been erased. 
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Ofc 


Format Control 


The system noun Ofc acts as a global argument to dyad v with a char- 
acter left argument (format by example). It specifies how ¥ deals with 
certain cases. Ofc is а six-item character list. The following list shows the 
value assigned in a clear workspace, and the significance each item has in 


formatting: 
Dfct11 


Ofe(2) 


Ofe(3) 


Dfct41 


Dfct5) 


Ofeté) 


Decimal point. Character to separate the integer part from 
the fractional part of a fraction. This character replaces. 
where it appears in а as а decimal point. 

Grouping separator. This character replaces , where it 
appears in а with digits on both sides, 

Fill to represent insignificant digits at positions marked in 
a by an 8. 

Character to fill an overflow field (one too small to contain 
the representation of a number in w). When OfcC4) is 
the character 0, an overflow in any field causes APL to 
reject the entire expression avc as a domain error. 


Marker for blank. Where this character appears in а as a 
controlled character (that is, embedded within the positions 
devoted to the number representation), the result contains. 
a blank. 


Proposed as character in the result to indicate a negative 
value. (Not implemented.) 


For more information on v, see Chapter 5, “Verbs”. 


Ofd 
Verb Definition 


Dyad Df a provides services for conversion between a verb and its character 
representation. а is a numeric item and selects one of the services described 
below. Из value must be a member of the set 1 2 3 6 7. 


List representation. w is the name of a user-defined verb, as 
a character list. The result is a character list (including new- 
line characters at the line boundaries) showing the definition. 
the way it looks when displayed by the V-editor: with line 
numbers enclosed in brackets, and a leading and closing V. 
When a is not the name of a verb, or has a locked definition, 
the result is an empty list. 


1 Dfa w 
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2 rd w 


з Dfa w 


6 Dfa w 


Table representation. w is the name of a user-defined verb 
as a character lisi. The result is a character table containing 
the canonical representation of the verb's definition, with one 
row for each line of the definition. The lines are shown the 
way they look when displayed by Der: flush-lefi, without 
line numbers, and without the opening and closing V. When 
а is not the name of a verb, or has a locked definition, the 
result is an empty table. 

Fix a verb from its representation. © is the character repre- 
sentation of a user-defined verb. It may be in either the table 
form retumed by Псг or 2 Dfd, or the list form retumed by 
1 Dfd, with successive lines separated by a newline charac- 
ter, with or without line numbers, with or without opening and 
dosing V. Blank lines are permitted within the representation. 


Side effect: The verb defined by wis fixed (that is, materialized 
in the workspace) in the same manner as U. A definition 
can be fixed provided the name shown in is available: that 
is, has no visible use, or its visible referent is to a verb (in 
which case the new definition replaces the old). 

When the name of the verb to be fixed has been localized 
in some verb that is currenily on the slate indicator stack, 
the newly defined verb is local to that verb. [t ceases to exist 
when the verb to which its name is local completes execution. 


Result; The name of the verb thus fixed, When for any 
reason the definition cannot be carried out, the result is а 
two-clement numeric list whose first element is a diagnostic 
code and second is an index in the argument of the error. The 
diagnostic codes are: 


1 
2 Definition error 
3 

4 Symbol table full 


Expunge names. w is a namelist, that is, either a list with 
successive names separated by blanks, or a table with one 
name per row. Each of the names in w is freed: that is, 
its visible referent is expunged so that the name is free for 
other uses. The result is a table containing those names that 
were not freed (because their referents cannot be expunged 
or because they were not well formed). Thus when 6 Ofd is 
successful, the result is an empty table. 


February 1993 
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7 Оға ш Lock verbs. w is a namelist (as defined above). Each of the 
verbs named in w is locked, The result is a table containing 
those names that were not locked (because their visible ref- 
erents were not verbs), Thus when 7 [fd is successful, the 
result is an empty table. 


Ofhold 
Hold Tied Files 


Coordinates access to shared files by different APL tasks. Shared compo- 
nent files are not supported and Ofhold has no effect. 


Ofi 
Input Format Conversion 


Monad Ofi returns the numeric values of the fields in a character list. It 
assumes that within c fields are delimited by blanks. 


‘The resull is a numeric list containing the value of each well-formed numeric 
field, and 0 for each other field. 


Ofi 1666 71.20 -5.5 .1 3141598 5 five' 
666 71.2 0 0.1 3.14159 0 
The value -5.5 is invalid because it contains a minus sign — instead of a 
negative sign 7. 
Ufi accepts any of the forms that may appear in default system output 
(or in the result of monad ¥). That includes integers, decimal fractions, е- 
formats, complex numbers, and numbers preceded by ^ to indicate negative 
values, Those are the only forms If recognizes; in particular, it does not 
consider well-formed a field that contains a currency symbol or embedded 
commas, ог that is enclosed in parentheses, and retums 0 for each such 
field. 


Ofi "Таке 3 spoons of 150 proof run! 
030015000 


Dfi ‘sent $3.00 for 6 kilos on 87/4/1' 
0006000 


To permit Of I to convert some common but otherwise unacceptable for- 
mats, techniques such as the following may be useful: 
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exte! 0123456789e.,- * 


inte! 0123456789 e. 
Dfi int lext i . 25 -6.25 8,9,10] 
0.25 6.25 8 9 10 


Use of Dfi with Ovi 
Since Ovi retums а Boolean result indicating which fields were well 
formed, the expression 
(Ovi лиз e 
returns only the values of the well-formed numbers. 


Ofm 
Function Monitor 


Ofm collects and reports measures of frequency of use, CPU time and 
elapsed time during the execution of user-defined verbs. 

CPU and elapsed time results on PC systems are erratic because of the very 
low resolution timer and can be misleading. 


Dyad Dfm 

Dyad a Ofm w sets or reports monitoring. w is a character array of names, 

each name in а 1-cell of w (that is, arranged along the last axis). Commonly, 

w is a table with one name per row. 

a is a numeric item indicating the data to be collected or reported. It 

applies to all the verbs named in w. The sign of a indicates whether you 

аге establishing monitoring or reporting data already collected: 

и non-negative Establishes which data should be collected during future 
excculions of the affected verbs. 

a negative Establishes which topics should be reported from the 

data already collected. 

The topic (collected or reported) is represented by the sum of the codes for 

the various possible topics. Since each code is a power of 2, cach topic 

can be enabled or reported independently of the others. 

Ofm acts on the visible (most local) definition of each verb. In case of 


an error during the execution of Ofm, the state of the workspace remains 
unchanged, 
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Tuming on any form of monitoring for a verb tums off any previous mon- 
itor setting for that verb. Tuming on any monitoring other than summary 
automatically generales summary monitoring. 


The numeric codes for the various monitoring reports are as follows: 


0° 


128 


2*0 


No monitoring. When а is zero, this (a) discontin- 
ues data collection, and (b) discards data from previous 
monitoring and frees the space used for its collection. 


Summary monitoring. Records the monitoring infor- 
mation for the topics associated with codes 2 through 
128 for the verb as a whole, without line-by-line break- 
down. 


Execution count. Records the number of times each 
line was executed. 

CPU/own. Records total CPU time on each line, but 
excluding user-defined verbs thal the line invokes. 


Elapsediown. Records total elapsed time on each line, 
but excluding user-defined verbs that the line invokes. 


€PUf/iotal. Records total CPU time on each line, in- 
cluding user-defined verbs that the line invokes. 


Elapseditotal. Records total elapsed time on each line, 
including user-defined verbs that the line invokes. 


CPUinon-monitored. Records CPU time for user- 
defined verbs that the line invokes and are not them- 
selves monitored. 
Elapsedinon-monitored. Records elapsed time in those. 
user-defined verbs that the line invokes but are not them- 
selves monitored. 


The result of dyad Ofm is an array with a cell for each name in w (that is, 
its frame-shape is ~14Pw). The cells are different, depending whether a is 
0, positive, or negative, as follows: 


а is zero A result cell is an item, reporting the former level of 


monitoring for each name in w. 


а is positive A result cell is an item, reporting the new monitoring 


status for each name. When the request to set monitor- 
ing is successful, each item in the result has the same 
value as a. When the system is unable to establish 
the monitoring requested (for example, because а name 


11-18 System Nouns and Verbs February 1993 


SHARP APL Reference Manual 


in @ does not refer to а visible user-defined verb), the 
corresponding element of the result is 0. 


«is 71 A result cell is а seven-item list. The items within 
that list are the summary values for cach of the reports 
corresponding to codes 241234567. 


а is even and negative Each result cell is a table, containing а linc-by-line re- 
port, with a row for each line of the verb. (For this 
reason, w may ask for а report on more than one verb 
if and only if the verbs have the same number of lines. 
A request for reports on verbs with different numbers 
of lines is rejected as a length error) 


Each result cell has a column for cach of the topics 
requested in а. A request for a report on а topic for 
which monitoring has not been enabled is rejected as a 
domain error. 

‘The values reported both for CPU time and elapsed time 
эге in seconds. 


Monad Ofm 


w is a table of names in the same manner as fora Dfm w. 


The result frame has shape 1 арса. Each cell is a numeric item indicating 
the monitoring satus of a name, encoded in the same way as the left 
argument of dyad Ofm. 


Storage Allocated to Monitoring Data 


Tuming on the monitor for a verb (by a Ofm w with a positive left argu- 
ment) causes the interpreter to allocate additional space in the verb defi- 
nition, in order to accumulate the requested data. The additional space is 
included in the result of 4 Dws. 

When you save a workspace, a verb's monitoring data is saved with it, and 


is loaded when the workspace is subsequently loaded, so that monitoring 
may span )save and Jload. 


However, copying, editing, fixing, or defining a definition? tums off 
monitoring and discards the space formerly allocated for data collection. 
When you pack the definition of а verb, monitoring is similarly discarded 
from the definition in the package. (The original verb is not changed; only 
the copy created inside the package.) 


‘That in, )copy, V-editar, Пех or 3 Ur Праве or Орраег. 
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You may set monitoring on a verb that is pendent or suspended. Monitor- 
ing takes effect at once, but (naturally) lacks data on the portion already 
executed. 


When an event is trapped, the cost of executing the recovery expression ів 
charged to the line thal was active when the event was trapped. 


You request monitoring of a verb whose definition is locked, but only with 
a left argument of 1 (summary). If you lock the definition of a verb for 
which monitoring was already in effect, monitoring is thereby tumed off 
(but you may then request summary monitoring). 


Monitoring a Recursive Definition 


You can monitor а recursive or re-invoked definition, The total CPU and 
elapsed time spent on lines including invoked verbs is equal to the time 
spent on the root verb. Suppose you have a verb foo that calls foo that 
in tum calls foo. You can think of that as though the invoked versions are 
different verbs: as though foo calls £002 that calls foo3, and you are 
only recording data for foo. 


When there is ло recursion, the column for Total CPU, including invoked 
verbs, is equal to the sum of 16 Ofm w. When there is recursion, the 
sum of 16 Ofm « is greater than the actual CPU time consumed by the 
verb. 


Similarly, when there is no recursion, the column indicating total elapsed 
seconds, including invoked verbs, is equal to the sum of 32 Ofm ©. 
When there is recursion, the sum of 32 Ofm wis greater than the actual 
elapsed time consumed by the verb. 
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Ofmt 
Format Output 
Dyad D£mt formats character and numeric data into a character table. The 


conventions for the left argument of [fmt resemble certain of those used 
in Fortran or Cobol. 


Format Phrases 
a is a character list divided into format phrases separated by commas. See 
Figure 11 -5 for a summary of format phrases. For example, the following 
contains three phrases: 
f-'16,£8.2,g< 999.99>' 


Each format phrase оета the appearance of a column of w. The number 
of phrases need not match the number of columns in о; the phrases are 
repeated cyclically as needed. 

Each phrase has а уре, indicated by a letter,’ such as the letters 1. f, or 
g in the preceding example. 

А constant field is reproduced in the output but does not correspond to any 
column of the data. A constant phrase is enclosed by the characters <> (or 
also by certain other characters), thus: 

ffe «Parti >,16,< Cost: »,f8.2* 


A tab phrase does not itself control a field of data, but controls the position 
in the result at which the next field starts, specified cither as a relative 
dislance forward or back from the end of the previous field, or as an absolute 
location in the result. 


The control nen эге all from the firat alphabet. 
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n a |» Character data. Print cach character in a field w positions wide, (Note 
that when w>1, this inserts blanks between adjacent letters.) 

n |q |e |wd | Exponential fraction. Print in a field w positions wide, with d significant 
digits. 

n | |c (wd | Fixed-point fraction. Print in a field w positions wide with d decimal 


digits. Trailing zeros always print. 


Integer. Leading zeron are represented by blanks unless the z qualifier is 
used. 


* x |р Relative reposition (“tab”). Start the next field at the position displaced p 
positions from the end of the preceding field. The displacement may be 
negative, in which case the next field may overwrite earlier ones. 

a m Absolute reposition (“tab”), Start the next field at position p (possibly 
over-writing preceding fields). 

«text» | Constant. Insert text in every row of the result. 


Picture. Insert the digits that represent the value (rounded to the nearest 
integer) into the “picture” text. Build the result as follows: Copy sext to the 
field. Then overlay the successive digits of the number's representation. 
Place the digits at the positions marked in the picture by 9 or 2, starting 
with the low-order digit in the right-most 9 or 2. In positions marked 2, 
represent leading ot trailing zeros by blanks. Where other text characlers 
are embedded between digits used in the result, keep them. Overlay right 
decorators to the right of the right-mos! digit used in the result, and left 
decorators to the left of the lefi-most digit used in the result. 


Key: 

Number of repetitions (optional). 
Qualifier (see Figure 11-6). 
Field width. 


Number of decimal digits (f format); 
number of significant digils (e format). 


Number of positions to displace next field. 


Figure 11-5 :Summary of Огте format phrases. 
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Repetition Factors 


A phrase or group of phrases may be preceded by a repetition factor. For 
example, 


9+'216,318.2,9< 999.99»! 


indicates that the first phrase (16) is to be used for two columns, the next 
(f8.2) for three columns, and the last (g< 999.99») for one. 


The repetition factor can apply to a set of consecutive phrases enclosed in 
parentheses. For example, 
9g*'2(16,3f8.2),g« 999.99 


indicates that the sequence of one column formatted by 16 and three 
columns formatted by £8.2 is to be repeated twice. 


Type and Shape of the Right Argument of Ufmt 


w is a numeric array or character array of rank no greater than 2, or list of 
one or more boxes containing such arrays. When w is a list or item, it is 
treated as if it were the one-column table ус. 


When w is formed as a succession of boxes, cach is disclosed, treated as 
a table, and its successive columns formatted in order from left to right. 
Columns need not have the same height; short columns in the result are 
padded with blank rows at the bottom to match the length of the highest. 


Shape of the Result of Ofmt 


The result retumed by Ofmt is always a character table. The number of 
rows is sufficient to accommodate the tallest column in w. 


In the result, successive bands of adjacent columns form fields correspond- 
ing to the phrases in the left argument а. Each field has the width specified 
by the corresponding phrase in а. There are no additional columns between 
fields, го the visual separation of fields in the displayed result is produced 
either by constant phrases in а, or by specifying formats that are wider than 
needed to represent the data. 


Qualifiers and Decorators 


Within each format phrase, to the left of the letter that identifies its type, you 
may insert various qualifiers or decorators. A qualifier (Sec Figure 11-6) 
provides additional rules, for example "insert commas between triplets of 
digits" or "leave this field entirely blank when the value being represented 
is zero.” * 
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A decorator (See Figure 11-7) is a piece of text altached to the repre- 
sentation of a number, usually to indicate its sign. Decorators precede the 
format phrase with which they are associaled. When used, decoration text 
appears to the right of the right-most digit used in the representation, or 
to the left of the left-most. For example, to enclose negalive numbers in 
parentheses, you need to include in the format phrase the decorators m (the 
left text of a negative number) and n (the right text of a negative number, 
thus: 


'me(»n«)»f8.2* Ofmt 7123.45 
(123.45) 
To preserve right-alignment, when you include decorators that appear to 
the right, you need to specify equal-length decorators for negative and non- 
negative numbers, thus: 


'me«(»ne)»p« »q« >£8.2 Üfmt 123.45 7123.45 
123.45 
(123.45) 


Alternatively, you may exploit decorators of different size to give different 
alignment to negative and non-negative values: 


- »f16.2! Dfmt 1 1 1 1 x 123.45 
123.45 
-123.45 
123.45 
-123.45 


The background decorator r first fills the field by repeating as necessary the 
character(s) specified, and then overwrites the field with the digits of the 
representation and the sign decorators. The effect is to leave the background 
text visible only in the positions unused by the representation. This is 
commonly used for “check protection,” as follows: 


IrKfakkaxxkukkxx> £12.21 Ufnt 12345.67 5.67 
$**12345.67 
S8. 60 
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Blank. Make the entire field blank when the value is zero. 


Commas. Insert commas between successive triplets of digits. (May not 
be used with g format.) 


Scale. Scale the result by displaying a value 106 times the value in w. 


Left justify. Left justify the representation within its field. (May not be 
used with g format.) 

Zeros, Print leading zeros or trailing zeros. (NB: In g format, z within the 
picture makes leading or trailing zeros blank.) 


Figure 11-6 :Summary of Ofme qualifiers. 


аем» NegativelLaft. Insert text to the left of the representation of a negative 
value. 


nstext> Negative/Right. Insert text to the right of the representation of a negative 
value. 


рек» Positive/Laft. Insert text to the left of the representation of a non-negative 
value. 


cen Positive/Right. Insert text to the right of the representation of a non-negative 
value, 


tex Background. First fill the field by cyclically repeating sexi across it. Then 
overwrite the digits and decoralors needed to represent the value. Leave 
the background text visible at positions that are not used for digits, sign, or 
decorators. 


sext». Symbol substitution. In each pair of characters within text, the first in- 
dicates a character used by default and the second the desired substitute. 
For example, s<, .,» displays blank where Ofme would otherwise put 
comma, and comma where D fmt would otherwise put dot. 


Figure 11-7 : Summary of Отс decorators. 
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^ 
۷ 


Text started with the left member of one of these pairs con- 
tinues until the malching right member of the pair. 


^ 
м 


^ 
v 


Gon 
pox 


Figure 11-8 :Text-delimiting characters for decorator text. 
Examples of Ofme 


n 
4163645361 0 74163645361 3645361 14163645361 


'bcm«-»k-2f14.2! Dfmt n 
41,636,453.61 


741,636,453.61 
36,453.61 
141,636,453.61 


'me(»n«)»q« »bck-2f17.2* Ofmt n 
41,636,453.61 


(41,636,453.61) 
36,453.61 
141,636,453.61 


phone >,9<2 (zzz) 999-9999»* Dfme n 
Phone 416) 364-5361 


Phone 000-0000 
Phone 7416) 364-5361 
Phone 364-5361 


Phone 1 (416) 364-5361 


11-26 System Nouns and Verbs February 1993 


SHARP APL Reference Manual 


[£x 
Fix a Definition 
Monad Ofx fixes (that is, makes available for execution) a user-defined 
verb from the characters of йз canonical representation. 


w is a character table containing the verb's definition in the form produced 
by Der. Bach row of the table representa а line of the definition, without 
leading or closing V and without line numbers. 


Side effect: The verb defined by w is fixed (that is, materialized in the 
workspace). A definition can be fixed provided the name shown in w is 
available; that is, has no visible use, or its visible referent is to а verb (in 
which case the new definition replaces the old). 


Result: The name of the verb thus fixed, When for any reason the definition 
cannot be carried out, the result is а numeric item identifying the line 
number“ thal contains the error. (Note that this is the same as an index 
into the rows of w when П1о*0. In 1-origin, line 1 of the proposed verb 
is located on row 2 of w, since the first row of w is devoted lo the header.) 
‘The result may indicate a row | greater than the index of the last row. That 
happens when w is empty, or the error is detected after the last row w has 
been processed. 


When the name of the verb to be fixed has been localized, the newly defined 
verb is local. Н ceases to exist when the verb to which it is local completes 
execution. 


3 Ofd provides similar capabilities. 
Ohold 


Hold Tied Files 


Coordinates access to shared files by different APL tasks. Shared compo- 
neni files are nol supported and Ino d has no effect. 


The return code from [fx differs fron thet returned by 3 009 which reports tbe character index into its list argument 
her than the line number. " 
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Dio 
Index Origin 
‘The noun О4о establishes the index origin used by several APL primitives. 


You may set Dio, but the only acceptable values are an item 1 or 0. Ina 
clear workspace, Dio is initially set to 1. 


When generating or using index values, APL assumes that they start with 
Oio. Compare the effects produced by leaving О1о at its default value, or 
setting it to the optional value 0: 


D *D1o«0 
1 0 
15 \5 
12345 01234 
- FxeS+15 
678910 56789 
* C30 х(31 
8 8 
xt5) x[51 
10 index error 
x(51 
^ 
xt01 xtol 
index error 5 
x0) 
^ 
373 373 
312 201 
6 23 11 4 76 e 23 114 76 
àv av 
$4132 43021 
x. [o. 51 v *. C0. 51 v 
6 7 8 9 10 5 6 
62311 4 6 6 23 
7 11 
8 4 
9 ^6 
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Verbs Affected by Dio 

The value of [110 is used in connection with: 

1 Both monad (to generate consecutive integers) and dyad (to ro- 
tum the indexes of w in a). 

? Both monad (roll) and dyad (deal) to generate random integers. 

at Bath monad(numesc) an dyad (character) grade up and grade 

"n. 

* Left argument of transpose. 

[..1 Selection by indexing. Indexing to select the axis of application 
of . NX. 

Olc 


Line Counter 


For each active user-defined verb, the system noun III shows the number 
of the line on which APL is currently working or (when execution is halted) 
is next to be executed when work resumes. 


For example, if at the moment APL is working on line 3 of verb report 
and report was invoked by line 5 of analyze, the value of Dic is 3 5. 


If you signal а weak interrupt while line 3 is active, APL completes execu- 
tion of the line and halts. The value of О1с is then 4 5. But if you signal 
a strong interrupt APL halts at once, perhaps without completing execution 
of line 3, and in that case Dic is still 3 5. 


Ос is set by APL; you can use it but not set it. The numbers in OIc are 
the numeric part of the state indicator (which shows both the name of each 
active verb and the current line number). Sec also 2 Ows 2 later in this 
chapter, and ) 51 in Chapter 12, “System Commands”, 


Like the stale indicator itself, О1с includes an entry not only for each 
active user-defined verb, but also for each pending use of а or Ehinput. 
The value reported for а or D is the line number of the line whose sentence 
invoked а or II (usually, the value that appears neat in the result of D1c). 
For example, if line 6 of analyze contains the phrase &'x tri y! and 
you interrupt execution before line 2 of cri has been completed, the state 
indicator looks like this: 


581 
T 11029 
* 
analyzeté] 
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And the value of Ic is 2 6 6. 


When a user-defined verb has been interrupted, the expression «(11 c is com- 
monly typed from the keyboard to mean “Resume execution with the next 
line in sequence.” This is a shorthand for «11 c (0010), since + considers 
only the first of the values in its argument. 


Olib 
Fite Library 
Monad Di ib retums the names of component files located in the current 
directory on the drive specified in the integer argument. Drive A is 1, B is 
2, C is 3, and so on. The current drive is indicated by 0, 
File Permission: Any. 
Result: A character table, with one row per file. Each row is a 22-element 
list, in which the first 10 characters are the drive number, right justified 
with leading blanks. The next character is blank and is followed by the file 
name. 
П1оаа 
Load a Workspace 
Па1оаа 
Load a Workspace Quietly 


Monads D10ad and Oqload have the same effect as the system command 
)load. Each replaces the present contents of the active workspace with 
the contents of a saved workspace. 

The argument is a character list (or item) identifying the workspace to 
be loaded (optionally preceded by the number of the library to which the 
‘workspace belongs). When you do not specify a library, your own is 
assumed. 

Кіз а moot question whether (oad or Dgload retums a result: when APL 
has executed Il od, the active workspace in which Dload was executed 
по longer exists. 


The two forms U1oad and Ogload differ only in whether they display 
the message saved followed by the date and time al which the saved 
workspace was saved. load causes the display, Ogload (q for “quiet”) 
does not. 


Following either Dload or Nad? APL automatically executes the line 
it finds stored as the visible value of 02x in the workspace just loaded. 
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Applications that make use of (11oad require some mechanism 10 pass 
control from the workspace that invoked load to the workspace loaded 
in consequence. Usually the invoking workspace depends upon the D1x of 
the new workspace to initiate action. 


Olx 


Latent Expression 


The system noun [12x is one you may set before saving a workspace in 
order to control the way the workspace starts each time it is loaded. At cach 
load, APL automatically executes the line it finds stored as the visible value 
of O1x, it in the same way that it would execute a line entered from the 
keyboard. 01x thus provides а mechanism for making an immediate and 
automatic start on such things as conditioning the workspace environment, 
starting or restarting an applicalion, or validating а user's access to ап 
application. 

A valid Ulx must be a character item or list. In a clear workspace, the 
initial value of (12x is *. 


Whenever you load a workspace (except when you load it by using the 
)xload command) APL executes A[]1x. If a sentence stored in 11x is 
invalid, APL reports an error and suspends execution in the same way that 
it would for a sentence entered in immediate execution. 


Onames 
Names of Tied Files 
The system noun (names provides a table with the names of tied files. 
File permission: None needed. 


Result: A character table of the file names currently tied, one file per row. 
The format of the result is the same as the result of 0.1 1b. Provided you do 
not Ocreate, Ost te, Ut e, erase. or Dunt 1e file between invoking 
Олатез and Chums, these two nouns have their values in the same order. 
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[inc 


Name Class of Identifiers 


Onl 


Monad Onc returns the name class of each of the names in ш. The argument 
is a table with one name per row. The result is a numeric list of classification. 
codes, describing the visible (that is, most local) referent of each name thus: 


Value — Class 
0 — Notinuse 
1 Label 
2 Noun 
з Verb 
4 Other 


A value of four indicates that the identifier is a distinguished name (be- 
ginning with a quad symbol) or a group, or that the argument is not a 
well-formed name. 


Name List 


Monad Un! retums a table of names in the workspace whose visible (that 
is, most local) use is in a particular class, is a numeric item or list 
indicaling the class of interest. 

The classes that appear in the right argument are identified by the numbers 
1 through 3, with the same meanings as in the result of Dnc, above. For 
example, Un! 1 2 retums a list of names whose visible use is as a label 
or a noun. 


The result is a table, with one name per row, arranged in alphabetical order 
(sorted so that all first-alphabet characters occur before any of the second- 
alphabet characters). 


Dyad Un! restricts the result to names whose first letter is a member of a. 
For example, 


"ху2' Onl 2 
retums a table of the nouns that begin with X, y or Z. 
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Onums 
Tie Numbers of Tied Files 
The system noun Dnums provides a list containing the tie numbers of files 
currently tied. The order of the items in Qnums matches the order of the 
rows in Qnames. 
File permission: None needed. 
Result: A list of the Че numbers of files currently Шей. Provided you do 


not Ocreate, Ost 1e, Ut ie, Derase, or unt 1e a file between invoking 
names and Onums, these two nouns have their values in the same order. 


[pack 
Build a Package 


The verb Ораск builds a package. A package is a noun containing а set 
of names, a set of name classes, and the referent of cach name. A referent 
may be а user-defined verb, a noun of any type (including a package), or 
undefined. 

Dyad а [pack w forms а one-member package whose referent is the noun 
or pronoun «2, to which is assigned the name indicated by the character list 
a. (A single-character name may be represented by an item.) 

For monad pack, w is a namelist, that iz, either а character item or list in 
which successive names are separated by blanks, or a table with one name 
per row. The result is a package containing the names of w together wilh 
the visible referent of each name. 

The representation of a verb within a package loses any function monitoring 
that may have been established by Ofm, but retains the original verb's trace- 
and stop-controls. 


Opdef 

Package Define 
Oppdef 

Protective Package Define 


Unde defines objects from within а package. For each of the names in 
package w, monad Орде causes the referent within the package to replace 
the visible referent outside. 
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Dyad a Üpdef w does the same thing, but only for the names included 
in namelist а, The namelist may be a lable with one name per row, or an 
item or list of names delimited by blanks. 


The objects thus defined replace the visible (that is, most local) referent of 
those names. When the name of an object (o be defined corresponds lo a 
name that has been localized in a verb that is currently executing, pendent, 
or suspended, the newly defined object is local, and ceases to exist when 
the verb to which ils name it local completes execution. 


Result: None for Opdef. 


Protective Definition 


Орех 


The extra р in the пате Oppdef stands for protective. Oppdet works in 
the same way as Lip de f. both for monad and for dyad, except that а name 
is defined from within package w only when it is not already in use outside. 
‘Thus existing uses of the names are "protected." 

The result of Oppdef is a table containing the names that were not suc- 


cessfully defined; when definition is completely successful, the resulting 
table has no rows. 


Package Expunge 


Opins 


The result of а Орех w is a package containing a subset of the names in 
ine package w, together with their referents. 

а is a namelist (that is, either a character list in which successive names are 
separated by blanks or a table with one name per row) containing names to 
be excluded from the result. It is not necessary that the names in а actually 
exist in w, 


Package Insert 


Dyed (pins merges two packages. Both a and w are packages. The result 
is а package containing the union of the sets of names in the argument 


packages. 

Where the same name occurs in both a and ш, the result takes the referent 
from w, Thus everything in w appears in the result, whereas а contributes 
only those names and referents not contained in w. 
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Oplock 
Package Lock 


Oplock takes а package argument and tums а package in which verb 
definitions are locked. 


‘The result оѓ monad Qplock is a package similar to w in which all verb 
definitions are locked. 


The result of dyad (1plock is a package identical to w, but in which verbs 
present in w and named in @ are locked. a is a namelist (that is, a character 
list of names separated by blanks, or a table with one name per row). 

In the result, all nouns, and verbs present in w but not named in d are 
unchanged. 


Opnames 
Package Names 


Monad Opnames reports the names contained in package w. The result is 
a table with one row for each name in w. The ordering of names in the 
result is fortuitous. 

When w is an empty package, the result is a 0-by-0 table. However, when 
wis not a package, the result is an empty list The expression РРОрпалез 
n thus provides a lest of whether а noun п is or is not а package. 


Орпс 
Package Name Class 


Црпс reports the name class of names in a package. The result is a numeric 
list, one item per name, representing the class of each name by an encoding 
similar to that retumed by Onc: 


Value Class 

Undefined, but in package 
Referent not in package 
[unused] 

Referent is noun 

Referen is verb 

[unused] 


Monad Opne retums the name class of every name in ©, in the same order 
as Opnames w. 


رت نودو س ھ 
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Opp 


For dyad Qpnc, а is a namelist, that is, either a character list in which 
successive names are separated by blanks, or a table with one name per 
row, The result contains the name class of each of the names in a, in the 
order that they appear in о. 


Print Precision 


‘The system noun Opp specifies the maximum number of significant digits, 
or print precision, provided by the system when it displays numeric floating- 
point data using either default output or ¥. 


You may set Орр as an integer item, not less than 1 nor greater than 18; in 
а clear workspace, the default value is 10. 


Upp has no effect on the display of any value that can be represented 
intemally as an integer, ог on а number that is not different from an integer, 
even when represented intemally in floating point. For example: 


Oppe3 
+3 
0.123 


1234.0000000000001 
1.23e3 


1234.0000000000000001 
1234 


When Opp+18, the result permits display of full internal precision, with ev- 
ery intemal floating-point value distinguishable from its nearest neighbors. 
The final digit may not be otherwise significant. 


Uppdef 
Protective Package Define 


Sec the discussion of Opdef, earlier in this chapter. 
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Ops 
Position and Spacing in Display 
The system noun [lps govems the formatting of an array of boxed items. 


In an array of rank 2 or greater, the alignment of rows and columns is 
preserved by padding a narrow item to match the width of the widest item 
in its column, or padding а short item to match the tallest item in its row. 
‘When the display of an item requires less space than reserved for it, the first 
two elements of Ops determine its position within the rectangle assigned 
to it. 


The second two items control the amount of additional space inserted verti- 
cally or horizontally to separate adjacent items. (These apply to any array, 
not just those of rank 2 or greater.) A negative value causes а box-drawing 
character 10 be placed at the vertical or horizontal edges of each box. 


The effects of the four elements of Прэ are as follows: 


Qps(1) Position in grid, first axis (vertical). 
71 At the top of the available space. 
0 Centered in the available space. 
1 Athe bottom of the available space. 


Qps(2] Postion in grid, second axis (horizontal). 
71 At the left of the available space. 
0 Centered in the available space. 
1 At the right of the available space. 


QpsC31 Vertical separation. 
Magnitude: the number of additional rows interpolated verti- 
cally in the result between the representations of successive 
rows of w, 
Vertical box boundaries. 
When [ps [31 is negative and has a magnitude of at least 2, 
the top and bottom edges of a box are marked by ^ at the top 
of the box and _ at the bottom. Where necessary, these box- 
edge characters overwrite the interpolated blank rows (which 
is why there must be at least (wo of them). Where necessary, 
the result contains extra rows at the top or bottom to accom- 
modate box boundarics that would otherwise project beyond 
the outer edges of the result. 

Qpst4] Horizontal separation. 
Magnitude: the number of additional columns interpolated 
horizontally in the result between the representations of suc- 
cessive columns of ш. 
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Opsel 


Horizontal box boundaries. 

When fips[4 is negative and has a magnitude of at least 
2, the left and right edges of a box are marked by | al each 
side, Where necessary, these box-edge characters overwrite 
the interpolated blank columns (which is why there must be at 
least two of them). Where necessary, the result contains extra 
columns at the left or right edges to accommodate box bound- 
aries that would otherwise project beyond the outer edges of 
the result. 


Package Select 


Opval 


The result of dyad [pse] is a package containing а subset of the names 
in the package w, together with their referents. 


a is a namelist, that is, cither a character list in which successive names 
are separated by blanks, or a table with one name per row. « specifies the 
names to be selected from package w (and which therefore appear in the 
result). 


Each name in а must actually occur in w (although it may exist there without 
а referent). APL rejects an expression in which a name in а does not exist 
in ш as a domain error. Monad Прве1 is undefined. 


Package Value 


Dyad Cpva! extracts the value of a noun from package w. a is a character 
list (or item) containing a single name. The name’s referent in c must exist 
and must be a noun. 


The result is the value of the noun а from in package w. For example: 


4-1 23 

be! Tom!» ! Dick'2! Harry" 
p*üpack ta bt 

2x'a! Opval p 


11-38 System Nouns and Verbs February 1993 


SHARP APL Reference Manual 


Ори 
Page Width 


The system noun [pw sets the maximum length of a line displayed by the 
session handler in response to default output, or output produced by ГЪ ог 
output. A line broken because it would exceed Орь is said to be folded. 
After a fold, each continuation segment is indented by six positions. For 
further discussion, see the section “Display of Nouns” in Chapter 3, “Nouns 
and Pronouns”, and the discussion of * in Chapter 5, “Verba”. 


You can set [lpw as an integer item not less than 30 nor greater than 250. 
In a clear workspace the default is 80. The current value of [pw is included 
when you save a workspace, and reactivated with the resl of the workspace 
when you subsequently load it. 


Ogload 
Load a Workspace Quietly 
See the description of Ill ond. earlier in this chapter. 


Ordac 
Read File Access Table 
Monad: Ordac . I. pol 
Read file access table of file tied to fe, with optional passnumber ри. 
File Permission: 256 or 4096. 


Result: The three-column integer library access table of a tied file. See the 
discussion of access controls in Chapter 10, "APL Component Files". 


Ordci 
Read File Component Information 
Monad: Ordci mm, cw [,pw] 
Read component Information for component en of the file tied to number 
їп with optional passnumber ри. 


The argument identifies a particular component in a particular file. The 
argument is a list of either two or three integers. The first contains the tie 
number of a tied file. The second is the number of a particular component 
in that file. If you specified a non-zero passnumber to tie the file, there 
must also be a third element containing that passnumber, 
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File Permission: 512. 
Result: a three-element numeric list containing the following information 
about the indicated file component: 


(Drdci w) [11 Size of the file component in bytes. The size r- 
includes both the data itself and the intemal 
data description, which specifies its type, rank, and 
shape. 
(Drdci u) [2) User that last wrote the component. 


(Orde! w) [31 Timestamp when the component was written. This 
is not supported and will be 0. 


Dread 
Read Component of a Tied File 
Monad: Dread tn, ex I, pal 


Read data object in component ся of file tied to tw, with optional passnum- 
ber pn. 


The right argument identifies a single component of a tied file. It is a list 
of two or three integers. 


The first clement contains the tie number of a tied file. 


‘The second clement contains the number of an existing component within 
that file. (If а component exists, its component number is less than the 
second element of the result of Osize, but not less than the first.) The 
system rejects an atiempt to refer to а non-existent file component with the 
message file index error. 

The third element, when required, is the passnumber. 

File permission: 1. 

Result: The value of the noun stored in the file component. 
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Пгепате 
Rename a Tied File 
Dyad: 'newname ' Urenane im l. e 
Rename the file tied to fw 10 йз name becomes mewname. 


where in is а tie number and pw the file passnumber (required only when. 
you tied the file using a passnumber). 


newname is a character list containing the new name proposed for the file; 
it must be a well-formed name, not currently in use. 


File Permission: 128 
Effect: The file is renamed. 
Result: None. 


Oreplace 
Replace Noun Stored in a Component 
Dyad: а Dreplace m, си I. pal 


Replace component си of file tied to in. with optional passnumber pr, with 
noun a. 

The right argument identifies the file tie and component number, and pass- 
number if required. The left argument is the noun whose value is to replace 
the value previously stored in that component. The right argument is a list 
of two or three integers. 


‘The first element contains the tie number of a tied file. 


‘The second element contains the number of an existing component within 
that file; see the discussion of the second element of the argument of Qread. 


The third element, when required, is the passnumbes. 
The left argument is а noun. It may have any size, shape, or type. There is 
no requirement that it have the same shape or type as the noun it replaces. 
Effect: The value of replaces the noun stored in the component. There 
is no requirement thal the new noun match the former value in type, rank, 
shape, or size. 
For the system to make the replacement, one of the following must be true: 
+ The storage already in use for the file docs not exceed the file's size 
limit 
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+ The new component requires no more space than the old one. 
File permission: 16. 
Result: None. 


[resize 
Set File Size Limit 


Url 


Dyad:a Oresize m [,pn] 


where in is a tie number and pm the passnumber (required only when you 
tied the file using а passnumbez). 


с is the desired new file size limit, as a numeric item. Ha value may not 
be less than the present actual size of the file. 


Effect: The file's size limit is revised as indicated, to the next larger mul- 
ple of physical record size. As long as the actual size of the file is not 
greater than the limit, the file system accepts а new component or а Te- 
placement for an exiting component. Once the file’s actual size exceeds the 
limit, the file system rejects an attempt to append, or to replace a component 
with a larger one, with the message file full. 


File Permission: 1024. 


Result: None. 


Random Link 


‘The system noun Or? is the seed value (or random link) used by the pseudo- 
random number generator. It is used in evaluating monadic 7 (roll) and 
dyad 7 (deal). Each time you invoke 7. as a side effect the system sels 
Url. Each time you invoke ? with the same argument and the same value 
of Or2 (and also of Dio), you get the same result. When you save а 
workspace, the value of Qr is saved as part of it. Each time that saved 
workspace is loaded, the same uses of 7 yields the same results. 


You may set Or before executing the random function 7 to assure: 


e Same results as on some other occasion (for example, to reproduce 
a test conducted earlier). For repeatable results, set Ox to whatever 
value it had before. 

. Different results on cach occasion (for example, when you repeatedly 
load a workspace but want to generate fresh random numbers each 
time). For unpredictable results, set Ur I to something unpredictable; 
for example: 
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Orle(+/0ts)+%/3+0es+1 


Range end Default: You can set Пг1 to any integer item greater than 0 
and less than 231-1. In a clear workspace, the default value is 16807 (which 
is 79). 


Algorithm: Аз cach pseudo-random number is generated, the seed (Пг1) 
is first assigned a new value and immediately used in the computation. 
The new value of 021 depends only on the previous value, and not on the 
arguments of 2. The visible value of Or! is set as: 


Orlep{mOrl 4 p*2147483647 4 m«16807 
This process is cyclic, and repeats after p-1 repetitions. See also the 
discussion of ? in Chapter 5, “Verbs”. For more information on the linear 
congruential algorithm used, sce The Art of Computer Programming, Volume 
2: Seminumerical Algorithms, D.E. Kruth, pages 9-10. 


signal 
Terminate and Signal Event 
The verb Us igna! is conditional: what it does depends on whether or 
not its argument is empty. Therefore it is frequently used in а conditional 
expression such as: 
signal test/event 
Given an empty w, signal does nothing. 
Result: None. 


When w is not empty, it must be a numeric item or onc-clement list. In 
that case, Osignal causes an immediate exit from the verb highest on the 
execution stack (thereby cutting back the stack by one level). In response 
to the signal, the interpreter sets the visible value of Der to record the 
event (just as it does from an event caused by an interrupt or an error in the 
definition). If a irap has been set for event w, the trap's recovery expression 
takes over. 


When the system sets Der following a signaled event, it inserts 4 090 in 
the first four positions of row 1. On the rest of row 1, it inserts the event 
name, The event name is: 


For dyad Qsignal The characters from a. 


| Notice thet this is equally true whan you type signa from the keyboard, axcept that thes in nothing wo cut back if 
you type Osignal while no verb is pending. 
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For monad (signal When w is опе of the standard event numbers, the 
standard event name (subject to ) n1t) associated 
with ©, Otherwise, blanks. 

On row 2 it inserts the sentence that contains the verb whose execution was 

terminated by signal. When that sentence is itself part of a user-defined 

verb, it shows the name of the verb and the number of the line that contains 
the sentence. 


On row 3 it inserts a caret pointing to the name of the verb whose execution. 
was terminated by signal. 


When there is no trap for event w, execution halts. The system displays an 
error message in the usual way; that is, (ler with the first four characters 
(the event number) omitted. 


See the section on event trapping in Chapter 9, “Event Handling”. 
Result: None. 


Osize 
Size of Tied File 


Monad: Озіге m [,pw] 


Size of the file tied 10 te, with optional pass number pr, returned as a the 
following four-clement numeric list: 


Result: This monadic verb retums a four-element numeric list describing 
the size of а file. The argument is the tie number of the file, followed (when 
required) by a pas mumber. The elements of the list describe the file’s size 
as follows: 


(Usize w)[1] Lowest component number for this file (that is, 1 for 
a file from which no leading components have been 
dropped). 

(size tz) Number of next component to be appended (that is, 
опе more than the number of the last existing compo- 
nen). 

(Dsize t) Total space now occupied by the file, in bytes. This 
number includes the file's internal directories, and may 
include dead space when a file has grown by replacing 
some components with components of different size. 

(size w)[4] File size limit, in bytes. A request to Dappend or 
replace with a larger record is honored only while 
the actual size is less than or equal to the limit. 


| 
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‘The number of components in the file tied to w is given by: 
1-/2*0si2e w 
File permission: 1 or 32768. 


Os tac 
Set File Access Table 
рум: а Ustac ён I. el 
Set access table to a for the file tied to . with optional passnumber ps. 
‘The right argument is the tie number of a file followed (when required) by 
а passnumber. 
‘The left argument is the proposed access table. It is а three-column ta- 


ble of integers. See the discussion of access tables in Chapter 10, “APL 
‘Component Files”. 


Effect: The left argument а becomes the access table for the file lied to w. 
File Permission: 8192 or 256. 
Result: None. 


Ostie 
Share Tie 


tie 
Exclusive Tie 
Dyads Ust le and Dt ie establish linkage between the name of an APL 
component file and the tie number used 10 refer to il from the active work- 
space. Ost ie permits other users to share the file at the same time (whereas 
Orie is exclusive). On a single user system Ust ie and Ut {e have the 
same effect. 


‘filename’ Ostie in [, pu] 
The right argument is integer, containing the proposed tie number, followed 
(when required) by the passnumber called for in the file’s access table. 


The proposed tie number must be a positive integer less than 29! and not 
in use as a tic number of another file. 
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When the right argument has two elements, the second is the passnumber. 
When the argument is a scalar or one-clement vector, a passnumber of 0 is 
understood. 


The left argument is a character list (or item) containing the name of an 
existing file. 


Watch out: It is poor practice to have the tic number appear as a constant 
in your programs. It is preferable to generate а tie number arbitrarily and 
then store it somewhere that the verbs requiring it can find it; for example, 
аз a global noun in the workspace. 


Effect: The le is tied. You may proceed to use the file. 
File permission: Any. 
Result: None. 


[trap 
Event Trap Control 


By setting the value of the system noun Ut rap, you specify the action to 
be taken if various events should occur. Events include errors, interrupts, 
and retum to immediate execution. See also Chapter 9, “Event Handling”. 


Ot rap is shared with the interpreter. In general, you set its value and the 
interpreter uses it. (However, the interpreter sets to '' any value that is 
syntactically invalid.) 

Ot rap may be either a table or a list. When it is a table, it has one row 
for each trap definition. When it is a list, the first character serves as & 
delimiter, and subsequent uses of the delimiter serve to separate the various 
definitions, The delimiter may not be а numeral, a blank, or the character 
-, which has a special use in the events field. 


In general, each trap definition (that is, each row of a table Ut rap. or 
each of the definitions separated by the delimiter in a list Ot rap) has the 
following form: 


List of event numbers D [Action [Recovery expression | 


The successive fields within а trap definition need no delimiter between 
them, but may be separated by any number of blanks. The fields are filled 
ош as follows. 
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[trap Event Numbers Field 


Events are identified by numerals. Successive numbers are separated by 
blanks, for example 2 14 5. ‘The order in which events are listed does not 
maler. A hyphen means “all events” in a range of numbers. For example 
1-11 means "Events 1, 11, and all events in between." Figure 16-4 shows 
all event numbers currently defined by APL. 


© means any event less than 1000; it has the same effect as 1-999. Setting 
a trap for 1000 applies to any event greater than 1000 and less than 2000; 
it has the same effect as 1001-1999. Where no numbers are stated, the 
trap definition applies to all events other than event 2001.7 


t rap Qualifier Field 


Either this field is emply, or it contains the letter o. The presence of an o 
makes the trap operale only at the verb's own level. That is, the trap works 
in the verb to which Пг гар is local, but not in verbs invoked within it. 


Note that o may be needed because, when verbs invoked within the current 
verb also localize Пггар, they may nevertheless fail to trap an event. 
Unless the о qualifier is included, this ПС гар may respond to an event that 
occurs in one of the sub-verbs. 


Watch out: You must separate the qualifier from the surrounding trap def- 
inition by at least one space. 

trap Action Field 
The action is indicated by a single letter, ав follows: 


s Stop Preempts other traps, if any. 

n Ned Exempts the current trap, leaves more global ones 
in effect. 

е Execule Executes the recovery expression in the current 
environment, 

c Сш and execute Cuts back the stale indicator, then executes. 

1 Immediate Resumes in mid-line (after the recovery expression 
has supplied the missing name). 

а Do One of four drastic measures. (See below.) 


Whether it applies to events 67 moot; whea they really occur, there is not much you can do about them. The 
trop does apply, however, if you Dei gna} those events. 51 упа 1 of these events is oot recommended, however — it 
tens o couse support staff and send them ooking for synem problema rade than application problems. 
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trap Recovery Expression 


The recovery expression is а line of APL in the same form as you might 
type it from the keyboard or assign it to 01x. 


In particular, with action е and c, if you want execution of the suspended 
verb to be resumed, you must include the branch arrow +. However, with 
action 1 (where the recovery expression supplies the definition of an unde- 
fined name) execution resumes at once when the name is defined, and the 
recovery expression should лог include branch arrow. 


If the recovery expression itself contains an error, that error cannot be 
trapped, and execution halls. 


The trap actions and their associated recovery expressions are listed in the 
following sections. 


Action s : Stop 


Stops execution when an event occurs. This action takes no recovery en- 
pression. 1n effect, it restores the default action of the interpreter, and is 


often used during debugging. 

Note that setting Ut rap- a s' is stronger than Dt rap- ' because mak- 
ing the visible Dt rap empty does not remove the action of other traps that 
may be shadowed. 


Action n : Next 


‘The action n instructs the interpreter to look no further in the present Ос rap, 
but to move on to the next (more global) Orrap. It has the effect of 
nullifying trap definitions in its own Ut rap that appear later in the trap 
definition. 

Like s, action n takes no recovery expression. 


Action i : Immediate 


Action 1 is usable only with event 6, value error. It is designed to 
supply the value of the undefined name and resume execution. A common 
use of this action is to implement demand paging systems. 

Action 1 is the only action that permits resumption of an interrupted line 
at a point other than the beginning. 

Action 1 requires a recovery expression. The recovery expression must 
not include a branch statement. It should do something to remedy the fact 
that an undefined name occurs in the sentence being executed (for example, 
read its definition from a file). 


11-48 System Nouns and Verbs February 1993 


SHARP APL Reference Manual 


When the recovery expression has been executed, the interpreter tries to re- 
sume execution of the sentence it was executing when it found an undefined 
name. 


If the name is still undefined after execution of the recovery expression, 
event б, value error is signaled again, but the 1 action will not act 
upon it. 


Action e : Execute 


The interpreter executes the recovery expression in the current environ- 
ment. To resume work after completing the remedial action, the recovery 
expression should include a sentence such аз c. 


Action c : Cut Back and Execute 


The interpreter aborts the execution of any verbs invoked by the verb that 
localized Ut rap (thereby cutting back the state indicator во the verb to 
which t zap is local is at the top), and then executes the recovery expres- 
sion. 


Action c differs from action е only when the operative trap is more global 
than the verb being executed Especially where the recovery expression 
uses a branch to resume execution, it is usually necessary to use action с 
rather than e. That is because the recovery expression is usually written 
as а branch to a destination that makes sense only in the verb thal set the 
Dtrap. For example, if verb v1 has a trap whose recovery expression is 


fixup o *retry 


the destination ret ry is perhaps a label on line 6 of v1. If verb v1 invokes 
v2 and v2 encounters an event which this trap traps, the effect with action 
e might be to go to line 6 of v2, when what you really want is to resume 
at line 6 of v1. 


Action d : Do 


This action invokes one of several actions that are not direcily attainable 
by executing an APL sentence (and hence not obtainable from actions e of 
c). 1n addition, action d is the only action permitted in response to event 
2001 (retum to immediate execution), which ів not otherwise a trappable 
event. 


‘The recovery expression may be empty, or may contain one of the following 
keywords: 


exit clear off 
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These actions have the following effects: 


d Action d with no keyword has no effect, other than to handle. 
the event and thus prevent more global Ut raps from being 
searched. 


d exit Causes execution to exit from the verb that contains the 
Derap, and retum to the environment in which that verb 
was invoked. 


d clear Clears the workspace. The former contents are lost. 


d off Clears the workspace and terminates the APL session. 
The action d off terminates the APL task without sav- 
ing a continue workspace, whereas (bounce saves con- 
tinue. 


Ots 
Timestamp 
The system noun It s contains the current date and lime of day (represented 
by the computer's intemal clock) as a seven-item numeric list containing 
the following information: 


Destil Year 
Dcst2) Month 
Псз[3] Day 
Пєз[41 Hour 


Ots[5} Minute 
Dts[6] Second 
06507) Millisecond 


The first three elements of Оса always indicate a date, and the last four 
elements always indicate a time of less than 24 hours. 


Пи1 


User Load 
This system noun reports 1 as the number of APL tasks. 
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Quntie 

Untie Tied Files 
Monad Dunt ie unties the files whose tie numbers are included in its argu- 
ment. w is a numeric list (or item) of numbers currently in use to tie files. 
Passnumbers are not included in w, 
The right argument is a numeric list (or item) of tie numbers. 
Passnumbers do not apply to Dunt ie, You do not include a passnumber 
even if you did specify one to tie the file. Any number appearing in the 
right argument w is assumed to represent a tie number. 
Effect: The files whose tie numbers appear in w are untied. Once you have 
untied a file, when that tie number appears in the argument of a file verb, 
the file system rejects the sentence with the message file tie error. 
‘There is no way to refer to the files thet were untied until you subsequently 
re- ie them. 
File permission: None. 
Result: None. 


Ovi 
Verification of Input Format 
Monad Ovi reports whether each field іп w is a valid numeric field. 
w is a character list (or item). Ovi treats w as a sequence of fields, in the 
same fashion as Uf 1 (described earlier in the chapter). 
‘The result is а Boolean list containing а 1 for each field that represents а 
well-formed number, and 0 for each field that does not. 


Ovi can be used in conjunction with [1£1 to provide a validity check on 
the input character list, as described in the discussion of Ofi. 


Owa 
Work Area Available 


The system noun Ома is a numeric item indicating the current amount of 
work area available in the active workspace (im bytes). It is computed 
by sublracting from the gross size allocaled to the workspace the amount 
currently in use for the definitions of nouns and verbs, the symbol table, 
and the execution stack and partial results associated with it 
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Ows 
Workspace information 


Dyad Ows reports a number of different items of information about the cur- 
rent state of the workspace. The information retumed in the result depends 
on the values of the two arguments, each of which is a numeric item. The 
possible values and the results associated with them are as follows: 


1 Ows w Namelists, ш is а numeric item identifying the class or classes 
of names to be included in the result ш must be a single item 
whose value is the sum of the numbers representing the desired 
classes. The classes are identified by powers of 2: 


1 Verb 

2 Noun 

4 Group 

8 Label 

The result is а character table containing one row for each visible 
name in any of the classes identified in w. 


2 Ows 1 Workspace ID. The result is a character list containing the name of 
the active workspace. When the workspace has not been named, 
the list is empty. Otherwise, it has 22 characters, in the same 
formal at returned by Ul 4b for the names of files. Although the 
format differs slightly, the information conveyed is the same as 
that displayed by the command )wsid- 


2 Dws 2 State indicator, The result is a character table containing one 
row for each item оп the state indicator, in the same format as 
displayed by the command ) s1. Each row contains the name of 
a user-defined verb, followed by a line number in brackets. A 
verb that is suspended is marked by as an asterisk following the 
closing bracket of the line number. The line number is the number 
of the line currently active (for a verb that is not suspended) or 
the number of the line next to be executed (for a verb that is 
suspended). The rows of the table show the most recently invoked. 
verbs at the top. Calls to 4 or to D input are shown in the result 
in the same way as user-defined verbs; each has a row on which 
the symbol 4 or О appears alone. 

2 Оез 3 Workspace environment. The result is а 12-element numeric list. 


A number of its elements are no longer in use and contain 71 
or 0, but are preserved to maintain consistent position for the 


а The effect of 1 Qus. ы is eusentially the tamo as thet of i1. In both cases, w identifies the classes 10 be included in 
the rasuk, but 1 Dus identifies them by a scheme different from бум of 007. 
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2 Ows 4 


3 Оиз ш 


4 Ows w 


others. The meaning of an element at cach position in the result 
is as follows: 

(2 Пиз 3)(1J Unused. 

(2 Qws 3)[2) Unused. 

(2 Gws 3)[31 Effective workspace size. This reports the ас- 
tual workspace size in bytes that is under the 
control of the APL application. This is useful 
information in the implementation of demand- 
paging schemes for APL objects in the work- 
space. 

(2 O 3)[4] Unused 

(2 Dus 3)[5] Unused. 

(2 Ows 3)[6) Unused. 

(2 Ows 3)C73 Current size of the symbol table. 

(2 Dus 3)С87 Symbols in use. 

(2 Ows 3)(9) Unused. 

(2 Ows 3)£10] Unused. 
(2 Dws 3)[11] Unused 
(2 Ows 3)(12] Unused 


Workspace information. The result describes the workspace by 
a threc-clement numeric list: 


(2 Ows 4)[1] Bytes needed to store the contents of the 


(2 Ows 4)(2) Unused. 
(2 Ows 4)[3] Timestamp as 60ths of a second since 
1960-03-01 00:00:00. 


Group members. «is the name of a group. The result is a char- 
acter table containing the names thal are members of the group. 


Storage space. The number of bytes of workspace storage re- 
quired to store each of the objects named in w. w is а namelist, 
either a list with successive names separated by blanks, or a ta- 
ble with one name per row. The result is the number of bytes 
that would be required to store the named object if it were the 
only instance in the workspace. (In fact, an object may be stored 
merely by pointing to another instance of the same value). The 
value includes space occupied by the header that the interpreter 
uses 10 describe the object's type, rank, and shape, but not the 
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space occupied by the entry for its name in the symbol table. If 
a name is that of a shared name, the result does not constitute а 


reference to the name. 


5 Ows ш Name class by stack level. w is а namelist, formed either as a 
list with successive names separated by blanks, or as table with 
one name per row. The result із a numeric table, having one row 
for each name in w, and one column for each level of the state 
indicator, plus an additional final column representing the global 
environment (not represented in the state indicator). Values wilhin 


the result as follows: 


71 Not localized at this level 

0 Localized at this level, not used 

1 Localized at this level, used as a verb 
2 Localized at this level, used as a noun 
4 
8 


Group 
Localized al this level, used as a label 


6 Ows t Noun Value. w is the name of a noun. The result is the value of — | 
the noun, or domain error if the name is not that of a noun. 
If the name is a shared name, it does not constitute a reference to 


the name. 
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1 2 System Commands 


System commands begin with a right parenthesis ), followed by the name 
of the command and any arguments. Command names may be spelled in 
either the first or second alphabet (that is, lowercase or capitals). 

You may enter a system command only when the interpreter is in immediate 
execution mode (including [input mode). You may not execute a system 
command from within the V-editor. A system command may not be part 


of a user-defined verb. 


)clear 

)continue 

)copy ws [:pass] [mm, xm, ...) 
Jdrop “we reel 

Jerase [name [name;... 1] 
ns [firsmame] 
)group grpmame (кате, name;... | 
)grp grpsame 

)grps [firsiname] 

)lib [drive] 

)load ws [:pass] 

off 

Урсору ws L: [mame, name, ...] 
)reset 
)save 
)51 
)sic 
)sinl 
)siv 
)symbols la] 
)vars [fesimame] 
)wsid [mewname] 
)xload ws [pass] 


[ws] [: pass] 


Clear workspace 

Save ws for resumption, and sign off 
Copy from saved to active Ws 
Discard saved workspace 

Erase global objects 

List verbs [starting wilh firstname] 
Form or disperse a group 

List members of a group. 

List groups [starting with firsiname] 
List workspaces 

Load and activate saved workspace 
‘Terminate session 

Protected copy from saved to active ws 
Synonym for) зіс 

Save a copy of the active workspace. 
State indicator 

State indicator clear 

State indicator with namelist 
Synonym for) sin1 

Size of symbol table 

List nouns [starting at firstname} 
Save-name of the active workspace 
Load workspace without executing 02x 


Figure 12-1 :List of system commands. 
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)clear 
Clear Active Workspace 


)clear 


Clears the active workspace and sets all system nouns to their default values. 


Conditions in a Clear Workspace 


Clearing the workspace restores several parameters to their default values. 
These are summarized in Figure 12-2. 


[Гез 

Parameter. Noun Value 

Comparison tolerance Det 1.41969769273941896714 
Format control Ofe ILLI 

Index origin Oto 1 

Line counter Ole 10 


Latent expression |00х |" 


Tie numbers in use | Drums | Unaffected 
Names of tied files names] Unaffected 


Printing precision — |Qpp 10 


Position and spacing | Ops 17101 
Page width üpw 80 
Random link ог! 16807 
Work area available | Owa As set by system startup 
Shared names None; previous offers are retracted 
Symbol table Space for 256 symbols 
(enn ушу with spece available) 
Workspace name None; reported as clear ws 


Figure 12-2 : Conditions in a clear workspace. 
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)continue 
Terminate APL Session for Restart 
continue 


‘Terminates APL and saves the active workspace under the name cont inue. 


) copy 
Copy Objects into Workspace 


)copy ws (:pass] [ name, name; ...] 


)pcopy 
Protected Copy into Workspace 

)pcopy ws L: pate] | name, тате, ] 
Copies objects from the saved workspace v into the active workspace. 
When no other names follow ws, all global user-defined names in the saved 
workspace are copied, but not system nouns, When other names follow ws, 
only the objects named are copied, and the list may include system nouns. 
For )pcopy, global objects already in the active workspace are protected; 
thal is, they remain as they were. If any objects were protected in this way, 
APL displays the message not copied: followed by a list of the names 
of objects that were not copied. 
Note that ) copy and )рсору deal with global objects only. They cannot 
copy the values of names that are localized in the saved workspace, and 
the values that materialize in the active workspace are global as well. 


)drop 
Delete a Workspace 
)drop ws [pass] 


Discards the saved workspace named ws from storage. The active work- 
space is unaffected, and so is ils name (which may be the same as the 
name of the workspace thus dropped). APL reports the date and time at 
which you dropped the workspace. If the workspace is locked, you need 
its password in order to drop it. 


When you know you want to drop a locked workspace, but you cannot 
remember the lock, the following will serve: 
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)clear 

)wsid lockedws 
)save 

drop lockedws 


)erase 
Erase Global Objects 
erase [name, ] [name,...] 


This command erases (expunges) the global definitions of the user-defined 
objects named in the list to the right. When an argument io) erase is the 
name of a group, both the group and all members of the group are erased. 


APL reports only the names of those objects explicitly mentioned in the ar- 
gumeni that it did лог erase. It displays their names in one or two messages, 
with the captions not found: or not erased:, as appropriate. 
An object is not erased if its name: 

. is not the name of a global object 

» refers to an verb in the state indicator) 

» refers to a system noun 


)fns 
Display Verb Names 
) fns { firstname) 


This command displays a list of names whose visible referent is a user- 
defined verb (function), in alphabetical order, horizontally across the screen. 
For alphabetization, a collating sequence is assumed in which all first- 
alphabet letters precede any second-alphabet letters. 

When the command is followed by a name, the list shows only those names 
thal occur in the alphabetized list at or after the position of that name. 


The names listed are the same as those retumed in the result of 022 3 ог 
1 Ows 1. 
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)group 
Alter a Group 
)group grpname (тате, name, ...] 


‘This command forms or disperses a group. When you form a group, the 
first name is the name the group is to have, and the names that follow are 
the names of its members. 


А group provides a shorthand way of referring to a set of global names, 
primarily so they can be either copied or erased without having lo mention 
them individually in the argument to the command ) copy or )erase. 
То add new members to an existing group grpaame, the syntax is: 


group grpmeme grpname newname, newname, ... 


)grp 
Display Group Member Names 
)grp grpsame 
Retums the list of names that are members of the group grp. 


)grps 
Display Names of Groups 
)grps [ firstname] 
Returns names of all groups in the active workspace. 
)lib 
Display Saved Workspace Names 
) lib [drive] 


Displays the names of saved workspaces in the current directory on the 
specified drive. The argument is 1 for drive A, 2 for B, 3 for C, and зо оп. 
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) load 
Activate a Workspace 
)1oad ws [;pass] 


Replaces the current active workspace by a duplicate of a saved workspace. 
The former contents of the active workspace are lost. 


The new contents must fit within the size of the active workspace. 


Following the ) load command, the interpreter immediately executes the 
latent expression stored as the visible value of the system noun Ox. 


The )х1оаа Variant 


The variant command )xJoad is similar to ) load, except that the in- 
terpreicr does not execute the latent expression. This is intended as a 
convenience in doing maintenance. 


)off 
Terminate APL Session 


dott 
This command terminates the APL session. 


) pcopy 
Protected Object Copy 
)pcopy 
See ) copy. 


)reset 
Clear SI Stack 


)reset 


This command is a synonym for ) sic, described below. 
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)save 
Save Active Workspace 


) saveLws) (:pass] 
This command saves a copy the active workspace. 


When you load а saved workspace, the active workspace has the same name 
as the saved workspace. The active workspace resulting from the command 
clear has по name. You may give your active workspace a name by the 
command )wsid. The name of the active workspace is a potential name. 
‘That is, it is the name under which APL would save your active workspace 
if you execute the command ) save. When the workspace as yet has no 
name, APL. rejects the command ) save with the message not saved, 
this ws is clear ws. 


If you try to assign a new name that duplicates the name of an existing 
saved workspace, it is rejected with the message not saved, this ws 
is XXX, where XXX is the existing name of the active workspace. 


After the ) save command is successfully carried out, the name under 
which you saved it becomes the name of the active workspace. 


Workspace Locks 


When you save a workspace, you may lock it. A locked workspace has 
а password of up to eight letters and/or numerals. You lock a workspace 
by entering a colon and the proposed password at the end of he) save 
command. Once a saved workspace has been locked, anyone (including 
you) making reference to the saved workspace or its contents must include 
а colon and the password in the command. 


)sic 
State Indicator Clear 
)sic 


This command abandons execution of al! suspended and pendent verbs, 
thereby clearing the stale indicator. The referent of any local name is lost. 


The effect of this command is different from that produced by the naked 
branch +. The branch abandons execution of the verb most recently started 
from immediate execution, together with all verbs that it may have invoked, 
but has no effect on verbs whose execution started earlier than that. See 
also Gt rap action d. 
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)si 
State indicator 
s1 
See ) siv. 


)sinl 
State Indicator with Namelist 


)sinl 
See )siv. 
)siv 
State Indicator with Namelist 
)siv 


This command causes APL to display a list of the verbs whose execution 
is pendent or suspended, and which are therefore on the execution stack (or 
state indicator). The list shows each level of execution on a separate line, 
showing the name of the verb and the number of the line that is currently 
active. 


Fora verb that is suspended, the display shows an asterisk. The line number 
in that case is ће number of the line next to be executed when execution 
is resumed. 


To illustrate, consider the folowing display: 


)si 
getta] * 
veri fy[1) 
теап[1] * 
analyzel3) 
report l21 


The verb get їз suspended, and has not completed execution of line 4. 
If resumed, it would start at the beginning of line 4. The verb get was 
invoked by line 1 of verify. The verb verify is waiting for get to 
complete, at which point verify will resume automatically ils work on 
the line indicated (line 1). 

The verb mean is also suspended, Evidently, following that suspension, 
rather thal resume its execution, you invoked veri ѓу (perhaps in an effort 
to examine the cause of the interruption in mean). 
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mean was invoked by a sentence on line 3 of analyze, which in lum 
was invoked by line 2 of report. report must have been invoked in a 
sentence entered from the keyboard during immediate execution. 

The verb 4 or a request for input via О appears in the state indicator in the 
same way as a user-defined verb, but without a line number. 


A table having the same appearance as ) 51 is retumed as the result of the 
verb 2 Qws 2. A list of the line numbers that appear is retumed by the 
verb Q1c (for line counter). 


Optionally, the command may include the letters n2 (for namelist), so that 
it is written )sin1. In that case, the display is organized in the same way, 
but also includes on each line a list of names local to the verb on that line. 
The information about the use of names is retumed in a different form by 
the verb 5 Dus. 


The obsolescent form ) stv (sate indicator with variables) is still accepted 
as a synonym for ) sinl. 


)symbols 
Set Symbol Table Size 
) symbols [а] 


Used without an argument, this command reports the current size of the 
symbol table. The symbol table must contain an entry for every name in 
the workspace, including the name of every user-defined noun and verb. 
It also contains every name referred to in a definition thal exists in the 
workspace. 


Used with numeric argument, this command causes the interpreter to set 
aside space in the workspace for a symbol table with the number of entries 
requested. (You may not request a table smaller than the number of names 
already in use; such a request is rejected with the message symbol table 
full) 


Since APL is able to increase the size of the symbol table automatically, it 
is not essential to do this. However, to avoid some inefficiencies in having 
to resize the table dynamically, it may be desirable to set the size large 
‘enough to accommodate all forsceable names. Conversely, when you know 
that few names are needed, you can make the symbol table smaller and 
thereby recover some of the space that would otherwise have been reserved 
for it. 


The symbol table size and number of symbols in use are also reported by 
2 Ows 3. 
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)vars 
Display Noun Names 
)vars | firsiname] 


This command causes APL to display a list of those names whose visible 
referent is а noun (variable), in alphabetical order, in the same format as 
)fns. The names are the same as those returned by Onl 2 or 1 Dws 2. 


)wsid 
Set Workspace Name 
)wsid [ mewname] 
Used with no argument, ) vs d displays the name of the active workspace. 


Used with an argument, ) vs fd assigns that name to the active workspace. 
The name of the active workspace is relevant only when you subsequently 
save the workspace. 


Watch out: If you set the name of the active workspace to the name of an 
already-saved workspace, you defeat APL's check against overwriting one 
of your saved workspaces. 


)xload 
Load Workspace without Autostart 


)xioad 
Sec the entry accompanying the description of) load. 
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Messages 


"When for some reason the. APL system encounters а problem and cannot 
proceed, it may display a message to indicate what has happened. This 
chapter describes what the various messages mean, the circumstances that 
may have produced them, and in some cases what remedial action you may 
be able to take. 


Sources of Messages and Trouble Reports 


Trouble reports A trouble report describes a problem encountered in 
regarding sysiem aitempling to carry out a system command or involv- 
commands ing the V-editor. 


Error or interrupt Each of these messages is caused by an event de- 

messages from the tected by the APL interpreter. The event is either 

APL an error in a line being executed or an interrupt sig- 

interpreter naled from outside the workspace (usually from the 
keyboard) while a line is being executed. Some (but 
not all) errors or interrupts can be intercepted by 
an appropriate setting of Ut rap. and are said to be 
trappable. 


| Trappable Errors and Interrupts 


i 


Each time a trappable event occurs, the system sets а new value for the 
system noun Der (event report). If the event is not trapped, execution halts, 
and the system displays a message. The message is identical to the content 
of Der, except that Der also contains an event number while the display 
does not. 


Following an untrapped error or interrupt, it may be possible to take cor- 
Tective action. If the message is in response to an entry from the keyboard, 
you may be able to correct the entry and resubmit it. If the message isin 
response to a problem that arose during execution of a user-defined verb, 
you may be able to correct the situation and resume execution. 
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Form of an Error Message 


When the APL interpreter encounters an untrapped error or interrupt, it 
sends you а three-part message. The first part is a general description of 
the type of problem (for example, syntax error or value error). 
Then it shows you the line containing the error. If the line is within a 
user-defined verb, it shows also the name of the verb and the number of 
the line on which it was working when it encountered the error. (When the 
verb's definition is locked, the system shows the verb's name and the line 
number, but not what is on the line.) 


Below that, on the third line, the system displays a caret. The caret points to 
the part of the line on which the interpreter was working when it encountered 
the error. For some errors, the system can point quite precisely to whal is 
wrong. For others, it is harder to point to what is wrong. For example, 
if you omitted a parenthesis, it is hard for the system to know where you 
should have put it. Instead, it shows where it was working when it found 
that parentheses do not maich. 


How Much Has Been Executed 


When the system displays a line of APL marked with a caret, the interpreter 
may have already executed part of the line, before it discovered the error, 
in general, you can tell what has been executed by the position of the caret. 
But it is prudent to check further; the caret’s position is not a definitive 
guide. An approximate rule is: 


+ A syntax error due to mismatched quotes, or inclusion of illegal 
characters as part of an unquoted part of a line, is signaled before any 
part of the line is executed. The caret appears one character past the 
right-most end of the line. 


. Within a line containing diamonds, statements to the right of the caret 
have not yet been executed. 


. Within the sentence to which the caret is pointing, verbs to the right 
of the caret have been executed. 


If the statements or verbs that have already been execuled produce some 
lasting change (for example, by respecifying the value of а noun or of 
a file component), you may have to make allowance for that before you 
re-execute the line. 
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Error Messages By Event Number 


This section lists the numbered “events” in order of event number. For cach 
event, it shows the associated message in English, French, and German. 


1 

ws full 
If the system were to execute the verb, or to copy the requested objects, it 
would require more space than is available in the workspace. 
Remedy: Soractimes it suffices to erase unwanted objects in the workspace. 
If the workspace contains suspended or pendent verbs, ) sic or- may help. 
Alternatively, you may need to alter the algorithm so that its internediale 
storage is not so extensive. (When this condition arises as the result of 
executing an APL expression, it is trappable as event 1. But ws full 
arising during) load, ) сору, or ) save is not trappable.) 


2 
syntax error 
The syntax analyzer has detected a statement appearing to violate the syn- 
tactic rules of the language. This could be for any of several reasons; for 
instance: 
« You have invoked a verb requiring а right argument without one. 
. You have unbalanced parentheses, brackets, or quotes. 


+ You have juxtaposed two names referring to nouns with no indication 
of а verb to be applied to them. 


3 

index error 
Within the brackets delimiting an index or axis, you have supplied а value 
that is not a valid index for the object being indexed. One possible cause 
of the problem is the wrong setting for the system noun Dio. 


4 

Yank error 
You have invoked a monadic verb whosc argument is limited to a particular 
rank with an argument of some other rank. Or you have executed a dyadic 
verb with arguments not corresponding in rank when they should. 


February 1993 Messages 13-3 


SHARP APL Reference Manual 


5 
length error 


You invoked a dyadic verb requiring its arguments to match in length, but 
your arguments do not match along the required axes. 


6 

value error 
You have referred to what appears to be the name of а noun or verb with no 
visible value. This might be because the name is shadowed during execution 
of a verb, or because the value really does not exist in the workspace. This 
message often arises because you have misspelled the name of the noun or 
verb. 


7 
format error 


You have supplied an invalid argument to Urmt. The system displays the 
portion of the left argument of Urmt that it was attempting to interpret, 


8 

result error 
An expression produced no result (in a context in which a result is expected). 
»'' and monadic 4 produce no result; neither does а user-defined verb 
whose header does not include a name for the result, or whose execution 
ends without ever assigning a value to the result. 


9 

si error 
You have changed the definition of a suspended verb in à way that changes 
the use of names so that APL cannot find the definition of a pendent verb. 


Remedy: Clear the state indicator by executing + as needed, or clear the 
state indicator completely by the command ) sic. 


11 

domain error 
You have invoked a verb, but the arguments you supplied to it arc outside. 
the verb's domain. Common examples: you have tried to divide by zero, 
of to catenate numbers and characters, or you have supplied a fractional 
argument to a verb defined only on integers. Consult the description of the 
verb in question for the criteria for ап acceptable argument. 
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15 

symbol table full 
‘The line you are trying to execute, or the package whose contents you are 
trying to define, ог the object you are trying to copy, requires the use of 
names for which there is no space in the symbol table, and the symbol table 
can no longer be automatically resized. This can only occur if the symbol 
table is already at its maximum size. 
Remedy: Correction will require resizing the workspace or reorganizing the 
application so that either a larger symbol table is possible or the need for 
so many distinct symbols is reduced. 


16 

nonce error 
The expression you entered appears valid, but APL is not presently (that 
is, for the nonce) equipped to execute it. This message may be encoun- 
tered if you execute a proposed verb that the system recognizes but whose 
implementation is not yet released. 


18 

file tie error 
You have specified a Че number as if it were tied when in fact it is not, or 
as if it were free lo be tied when in fact it is already tied. 


9 
file access error 


You have tried to Че a file to which you do not have access, or to Че or 
use it without the correct passnumber, or to use it with a verb for which 
the file’s access matrix does not give you authorization. 


20 
file index error 


You have invoked Dread, replace, Urdc i. or drop with an argument 
referring to а nonexistent file component, or you have altempted to append 
а component number greater than 214748647 to а file. 


21 

file full 
You have attempted to append a new component to a file whose current 
size already exceeds the number of bytes reserved for that file. 


Remedy: Resize the file. See the description of Огеѕі ге in Chapter 11, 
“System Nouns and Verbs”. 
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file 


25 
file 


file 


Note: You might expect that replacing some of the existing components 
with data requiring less space would decrease the total storage of the file. 
While that is true in the long run, it does not always reduce the total size 
immediately. That is because the physical storage freed by doing that may 
not be available to the new components you want to append until after the 
operations staff has performed periodic file maintenance. 


name error 


The left argument of Dt ѓе, Ost ie, or Ücreate is not a valid name, or, 
where the verb must refer to an existing file, not the name of an existing 
file. In the case of Dcreate, the file name may already exist. 


damaged 
The file you are trying to use has been marked damaged. 


tied 
You have altempied to бе a file you have already tied. 


system hardware error 


‘The system is unable to read correctly from the physical device storing the 
component you have asked (0 read or write. 


system error 
Something is seriously wrong with the file. 


system not available 


You have invoked a file verb other than Davai! when the file system is 
not running. 


system ties used up 
The system has tied the maximum allowed number of distinct files. 
Remedy: Uniie files that you are not currently using. 
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31 
file tie quota used up 


The system has tied the maximum allowed number of distinct files. 
Remedy: Untie files that you arc not currently using. 


38 

file component damaged 
You have attempted to read a file component that is unreadable because of 
an inconsistent file system internal directory. 


ws locked 
While referring to а workspace, the password you have supplied docs not 
match the password with which the workspace was saved. This could arise 
either because the workspace requires a password but you did not supply 
the right one, or because it has no password and you did supply one. If 
your reference to the workspace occurred in an APL expression (that is, 
one invoking D10ad or Qq1oad), this event is trappable as event 45. But 
if your reference was in a system command, it is not trappable. (When this 
happens following a command) load or) copy, Der is not set. But when 
it happens in response to Q1oad or Ogload, Der is set to show event 45.) 


46 

ws not found 
The workspace you requested does not exist. If your reference to the 
workspace occurred in an APL expression, this event is trappable as event 
46. But if your reference was in a system command, it is not trappable. 


47 
ws not readable 


The system is unable to read the saved workspace. 


68 

system error, clear ws 
The system has encountered an undiagnosed error while executing a com- 
mand or an APL statement in your workspace and the system clears your 
workspace. 
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72 
interface quota exhausted 


You have attempted to offer to share more names at one time than the APL. 
system allows. 


Remedy: Retract some shares. 


73 
no shares 


You have invoked a shared name verb when the system's Shared Variable 
Processor is not running. 


74 

interface capacity 

exceeded 
You have attempted to assign to shared variable а value requiring more 
storage space than the system's Shared Variable Processor can accept. 
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System Nouns with Invalid Values 


The following events arise when the indicated system noun has been given 
an unacceptable value. (See the description of the noun in question in 


Ops 


85 
Ofc 


error 


error 


error 


error 


error 


error 


error 


Chapter 11, “System Nouns and Verbs") 


95 


ws not writable 
You have attempted to) save a workspace, but a hardware failure has 


prevented it from completing successfully. 
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Interrupt Events 


1001 

stop 
While executing a user-defined verb, APL has encountered a line for which 
а stop has been set (sce “Stop and Trace Controls” in Chapter 8, “Control 
of Execution"). 


1002 
attention 


While executing a user-defined verb, APL has a received a weak interrupt. 
Execution halts at the beginning of the next line to be executed. 


1003 
interrupt 


‘The system has received a strong interrupt signal. It has cut short execution 
of the line it was executing. 


Watch out: Part of the line may have been executed. An instruction to 
store data occurring within this statement and to the right of the caret may 
have been carried out already. That includes assigning a new value 10 4 
noun or storing something in a file. If you consider re-executing the line, 
notice that that storage (noun or file component) may already have received 
a new value, and the line may not be trivially re-executable. 


The system discriminates several different interrupts, according to the in- 
terupted activity: 
1004 Interrupt during O- or l'-input. 
1005 Interrupt while awaiting à shared name access. 
1006 Interrupt during a file operation. 
1007 Interrupt during file backup. 
1003 An interrupt during execution, but not 1005, 1006, or 1007. 
1004 
input interrupt 
You have interrupted input from the keyboard (in response to О or 0). 
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